From ast-index
Performs fast structural code searches for symbols, classes, usages, implementations, hierarchies, and dependencies in polyglot projects using ast-index CLI.
npx claudepluginhub defendend/claude-ast-index-search --plugin ast-indexThis skill uses the workspace's default tool permissions.
Fast native Rust CLI for structural code search in Android/Kotlin/Java, iOS/Swift/ObjC, Dart/Flutter, TypeScript/JavaScript, Rust, Ruby, C#, Scala, PHP, Perl, Python, Go, C++, and Proto projects using SQLite + FTS5 index.
references/android-commands.mdreferences/cpp-commands.mdreferences/csharp-commands.mdreferences/dart-commands.mdreferences/go-commands.mdreferences/ios-commands.mdreferences/matlab-commands.mdreferences/module-commands.mdreferences/perl-commands.mdreferences/proto-commands.mdreferences/python-commands.mdreferences/ruby-commands.mdreferences/rust-commands.mdreferences/typescript-commands.mdreferences/wsdl-commands.mdGuides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Generates original PNG/PDF visual art via design philosophy manifestos for posters, graphics, and static designs on user request.
Fast native Rust CLI for structural code search in Android/Kotlin/Java, iOS/Swift/ObjC, Dart/Flutter, TypeScript/JavaScript, Rust, Ruby, C#, Scala, PHP, Perl, Python, Go, C++, and Proto projects using SQLite + FTS5 index.
ALWAYS use ast-index FIRST for any code search task. These rules are mandatory:
"some text")Why: ast-index is 17-69x faster than grep (1-10ms vs 200ms-3s) and returns structured, accurate results.
Install the CLI before use:
brew tap defendend/ast-index
brew install ast-index
Initialize index in project root:
cd /path/to/project
ast-index rebuild
The index is stored at ~/Library/Caches/ast-index/<project-hash>/index.db (macOS) or ~/.cache/ast-index/<project-hash>/index.db (Linux). Rebuild deletes the DB file entirely and creates a fresh index.
| Platform | Languages | Module System |
|---|---|---|
| Android/Java | Kotlin, Java | Gradle (build.gradle.kts), Maven (pom.xml) |
| iOS | Swift, Objective-C | SPM (Package.swift) |
| Web | TypeScript, JavaScript, React, Vue, Svelte | package.json |
| Rust | Rust | Cargo.toml |
| Ruby | Ruby, Rails, RSpec | Gemfile |
| .NET | C#, ASP.NET, Unity | *.csproj |
| Dart/Flutter | Dart | pubspec.yaml |
| Scala | Scala | Bazel (WORKSPACE, BUILD) |
| PHP | PHP | composer.json |
| Perl | Perl | Makefile.PL, Build.PL |
| Python | Python | None (*.py files) |
| Go | Go | None (*.go files) |
| Proto | Protocol Buffers (proto2/proto3) | None (*.proto files) |
| WSDL | WSDL, XSD | None (*.wsdl, *.xsd files) |
| C/C++ | C, C++ (JNI, uservices) | None (*.cpp, *.h, *.hpp files) |
| Godot | GDScript | project.godot |
| Mixed | All above | All |
Project type is auto-detected by marker files (build.gradle.kts, Package.swift, Makefile.PL, etc.). Python, Go, Proto, WSDL, and C++ files are indexed alongside main project type.
search - Perform universal search across files, symbols, and modules simultaneously.
ast-index search "Payment" # Finds files, classes, functions matching "Payment"
ast-index search "ViewModel" # Returns files, symbols, modules in ranked order
ast-index search "Store" --fuzzy # Fuzzy: exact → prefix → contains matching
ast-index search "Handler" --module "core/" # Search within a module
ast-index search "UserService" # Find Java/Spring services
ast-index search "@RestController" # Find Spring REST controllers (annotation search)
ast-index search "@GetMapping" # Find GET endpoint mappings
file - Find files by name pattern.
ast-index file "Fragment.kt" # Find files ending with Fragment.kt
ast-index file "ViewController" # Find iOS view controllers
symbol - Find symbols (classes, interfaces, functions, properties) by name.
ast-index symbol "PaymentInteractor" # Find exact symbol
ast-index symbol "Presenter" # Find all presenters
ast-index symbol "Store" --fuzzy # Fuzzy: exact → prefix → contains matching
ast-index symbol "Mapper" --in-file "payments/" --limit 10 # Scoped search
ast-index symbol "@Service" # Find all @Service annotations
class - Find class, interface, or protocol definitions.
ast-index class "BaseFragment" # Find Android base fragment
ast-index class "UIViewController" # Find iOS view controller subclass
ast-index class "Store" --fuzzy # Find all classes containing "Store"
ast-index class "Repository" --module "features/payments" # Filter by module
ast-index class "UserController" # Find Java/Spring controller class
usages - Find all places where a symbol is used. Critical for refactoring.
ast-index usages "PaymentRepository" # Find all usages of repository
ast-index usages "onClick" # Find all click handler usages
ast-index usages "fetchData" --in-file "src/api/" # Scoped to file path
ast-index usages "Repository" --module "features/auth" --limit 100
Performance: ~8ms for indexed symbols.
refs - Show cross-references for a symbol: definitions, imports, and usages in one view.
ast-index refs "PaymentRepository" # Definitions + imports + usages
ast-index refs "BaseFragment" --limit 10 # Limit results per section
implementations - Find all classes that extend or implement a given class/interface/protocol. Supports partial name matching with relevance ranking (exact → suffix → contains).
ast-index implementations "BasePresenter" # Find all presenter implementations
ast-index implementations "Repository" # Find repository implementations (exact match)
ast-index implementations "Service" # Partial: finds UserService, PaymentService impls too
ast-index implementations "ViewModel" --module "features/" # Scoped to module
hierarchy - Display complete class hierarchy tree.
ast-index hierarchy "BaseFragment" # Show fragment inheritance tree
callers - Find all places that call a specific function.
ast-index callers "onClick" # Find all onClick calls
ast-index callers "fetchUser" # Find API call sites
call-tree - Show complete call hierarchy going UP (who calls the callers). Supports Kotlin, Java, Swift, Perl, ObjC.
ast-index call-tree "processPayment" --depth 3 --limit 10
ast-index call-tree "getUsers" # Java: finds callers of getUsers() method
imports - List all imports in a specific file.
ast-index imports "path/to/File.kt" # Show Kotlin file imports
outline - Show all symbols defined in a file. Uses tree-sitter for accurate parsing of all supported languages.
ast-index outline "PaymentFragment.kt" # Show Kotlin fragment structure
ast-index outline "UserController.java" # Show Java controller methods
ast-index outline "App.tsx" # Show TypeScript/React components and functions
ast-index outline "handler.rs" # Show Rust structs, impls, functions
todo - Find TODO/FIXME/HACK comments in code.
ast-index todo # Find all TODO comments
ast-index todo --limit 10 # Limit results
deprecated - Find @Deprecated annotations.
ast-index deprecated # Find deprecated items
unused-symbols - Find potentially unused exported symbols.
ast-index unused-symbols --module path/to/module # In specific module
ast-index unused-symbols --export-only # Only exported (public) symbols
changed - Show symbols changed in git/arc diff. Auto-detects VCS and base branch.
ast-index changed # Auto: trunk (arc) or origin/main (git)
ast-index changed --base main # Explicit base branch
ast-index changed --base trunk # For arc projects
api - Show public API of a module. Accepts module path or module name (dots converted to slashes).
ast-index api "path/to/module" # By path
ast-index api "module.name" # By module name (dots → slashes)
map - Show compact project overview: top directories by size with symbol kind counts. Use --module to drill down into a specific area with full class/inheritance details.
ast-index map # Summary: top 50 dirs with kind counts (~54 lines)
ast-index map --limit 20 # Show only top 20 directories
ast-index map --module features/payments # Detailed: classes with inheritance for a module
ast-index map --module src/core --per-dir 10 # More symbols per directory in detailed mode
ast-index map --format json # JSON output
Summary mode output (default, no --module):
Project: Android (Kotlin/Java) | 29144 files | 859 modules | top 50 of 728 dirs
features/taxi_order/impl/ 1626 files | 371 iface, 94 obj, 1834 cls
features/masstransit/impl/ 862 files | 165 obj, 1261 cls, 280 iface
Detailed mode output (with --module):
features/payments/impl/ (250 files)
PaymentInteractor : class > BaseInteractor
PaymentRepository : interface
PaymentMapper : class
conventions - Auto-detect architecture patterns, frameworks, and naming conventions from the indexed codebase. Runs read-only SQL queries — no file scanning needed.
ast-index conventions # Text output (~30 lines)
ast-index conventions --format json # JSON output
Detects:
Most search commands (search, symbol, class, usages, implementations) support:
| Flag | Description |
|---|---|
--fuzzy | Fuzzy search: exact match → prefix match → contains match |
--in-file <PATH> | Filter results by file path (substring match) |
--module <PATH> | Filter results by module path (substring match) |
--limit <N> | Max results to return |
--format json | JSON output for structured processing |
When to use --fuzzy: When you don't know the exact name. ast-index class "Store" --fuzzy finds Store, StoreImpl, AppStore, DataStoreRepository, etc. The --fuzzy flag performs three-stage matching: exact match first, then prefix match, then contains match.
ast-index rebuild # Full rebuild with dependencies
ast-index rebuild --no-deps # Skip module dependency indexing
ast-index rebuild --no-ignore # Include gitignored files (build/, etc.)
ast-index rebuild --sub-projects # Index each sub-project separately (large monorepos)
ast-index rebuild -j 32 # Use 32 threads (for network/FUSE filesystems)
ast-index rebuild -v # Verbose logging with timing per step
ast-index update # Incremental update (changed files only)
ast-index stats # Show index statistics
ast-index clear # Delete index for current project
ast-index restore /path/to/index.db # Restore index from a .db file
ast-index watch # Watch for file changes and auto-update index
When running search from a subdirectory, results are automatically limited to that subtree (the index DB in cache is used to detect the project root):
cd /project/root
ast-index rebuild # Index entire project, creates .ast-index-root
ast-index search "Payment" # Finds results across entire project
cd /project/root/services/payments
ast-index search "Payment" # Only finds results within services/payments/
ast-index class "PaymentService" # Only classes in services/payments/ subtree
This works with all search commands: search, symbol, class, implementations, usages.
Add additional source roots for monorepos or multi-project setups. Extra roots are indexed alongside the primary project and their module dependencies are included.
ast-index add-root /path/to/other/source # Add source root (warns on overlap)
ast-index add-root ./subdir --force # Force add even if inside project root
ast-index remove-root /path/to/other/source # Remove source root
ast-index list-roots # List configured roots
ast-index version # Show CLI version
ast-index help # Show help message
ast-index help <command> # Show help for specific command
ast-index install-claude-plugin # Install Claude Code plugin to ~/.claude/plugins/
For complex analysis that requires combining multiple queries, filtering, or aggregation — use direct SQL access instead of chaining multiple commands.
Structural code search using AST patterns. Requires sg (ast-grep) installed.
# Simple pattern matching
ast-index agrep "router.launch($$$)" --lang kotlin
ast-index agrep "@Inject constructor($$$)" --lang kotlin
ast-index agrep "suspend fun $NAME($$$)" --lang kotlin
# Find classes extending a specific base
ast-index agrep "class $NAME : BasePresenter($$$)" --lang kotlin
# Find async functions (Swift)
ast-index agrep "func $NAME($$$) async" --lang swift
# Find React components
ast-index agrep "export default function $NAME($$$)" --lang typescript
# JSON output for programmatic use
ast-index agrep "@Composable fun $NAME($$$)" --lang kotlin --json
Pattern syntax (ast-grep):
$NAME — matches a single AST node (captures as metavariable)$$$ — matches zero or more AST nodes (variadic)When to use agrep vs built-in commands:
composables, inject, suspend → use built-in (faster, pre-configured)agrep# Execute any SELECT query against the index database (JSON output)
ast-index query "SELECT s.name, s.kind, f.path FROM symbols s JOIN files f ON s.file_id = f.id WHERE s.kind = 'class'"
# With limit
ast-index query "SELECT * FROM symbols WHERE name LIKE '%Service%'" --limit 50
# Complex joins — find classes that implement an interface but have no usages
ast-index query "SELECT s.name, f.path FROM symbols s JOIN files f ON s.file_id = f.id JOIN inheritance i ON s.id = i.child_id WHERE i.parent_name = 'Repository' AND s.name NOT IN (SELECT name FROM refs)"
# Find files with most symbols (complexity hotspots)
ast-index query "SELECT f.path, COUNT(*) as sym_count FROM symbols s JOIN files f ON s.file_id = f.id GROUP BY f.id ORDER BY sym_count DESC LIMIT 20"
# Find unused classes (defined but never referenced)
ast-index query "SELECT s.name, s.kind, f.path FROM symbols s JOIN files f ON s.file_id = f.id WHERE s.kind IN ('class', 'interface') AND s.name NOT IN (SELECT name FROM refs) AND s.name NOT IN (SELECT parent_name FROM inheritance)"
# Module dependency analysis — find modules with most dependencies
ast-index query "SELECT m.name, COUNT(*) as dep_count FROM module_deps md JOIN modules m ON md.module_id = m.id GROUP BY m.id ORDER BY dep_count DESC"
# CTE — transitive dependency chain
ast-index query "WITH RECURSIVE chain AS (SELECT md.dep_module_id, m.name, 1 as depth FROM module_deps md JOIN modules m ON md.dep_module_id = m.id WHERE md.module_id = (SELECT id FROM modules WHERE name LIKE '%payments%') UNION ALL SELECT md.dep_module_id, m.name, c.depth + 1 FROM chain c JOIN module_deps md ON md.module_id = c.dep_module_id JOIN modules m ON md.dep_module_id = m.id WHERE c.depth < 5) SELECT DISTINCT name, depth FROM chain ORDER BY depth, name"
Security: Only SELECT, WITH, and EXPLAIN queries allowed. Mutations (INSERT, UPDATE, DELETE, DROP) are blocked.
# Show all tables with columns and row counts (JSON)
ast-index schema
Key tables:
| Table | Description | Key columns |
|---|---|---|
files | Indexed source files | path, mtime, size |
symbols | Classes, functions, properties, etc. | name, kind, line, file_id, signature |
symbols_fts | FTS5 full-text search on symbols | name, signature |
inheritance | Parent-child type relationships | child_id, parent_name, kind |
refs | Symbol references/usages | name, line, file_id, context |
modules | Build modules (Gradle, Maven, etc.) | name, path, kind |
module_deps | Module → module dependencies | module_id, dep_module_id |
transitive_deps | Pre-computed transitive deps | module_id, dependency_id, depth |
xml_usages | Android XML layout class usages | class_name, file_path |
resources | Android resource definitions | type, name, file_path |
# Get the SQLite database path for external tools
ast-index db-path
# Output: /Users/me/.cache/ast-index/abc123/index.db
Use this path with any language that supports SQLite:
import sqlite3, json
db_path = subprocess.check_output(["ast-index", "db-path"]).decode().strip()
conn = sqlite3.connect(db_path)
# Example: find all classes implementing an interface with no references
unused_impls = conn.execute("""
SELECT s.name, f.path, i.parent_name
FROM symbols s
JOIN files f ON s.file_id = f.id
JOIN inheritance i ON s.id = i.child_id
WHERE s.name NOT IN (SELECT name FROM refs)
ORDER BY i.parent_name, s.name
""").fetchall()
for name, path, parent in unused_impls:
print(f" {name} implements {parent} — {path}")
When to use query vs predefined commands:
search, class, usages (faster, formatted output)query (one call instead of N)db-path + direct SQLite access| Command | Time | Notes |
|---|---|---|
| search | ~10ms | Indexed FTS5 search |
| class | ~1ms | Direct index lookup |
| usages | ~8ms | Indexed reference search |
| imports | ~0.3ms | File-based lookup |
| callers | ~1s | Grep-based search |
| map | ~1-3s | SQL aggregation (scales with project size) |
| conventions | ~1-4s | SQL aggregation + import matching |
| rebuild | ~25s–5m | Full project indexing (depends on size) |
Consult: references/android-commands.md
Java parser indexes: classes, interfaces, enums, methods, constructors, fields, and significant annotations (@RestController, @Service, @Repository, @Component, @Entity, @GetMapping, @PostMapping, @Autowired, @Override, @Transactional, @SpringBootApplication, @Test, @Inject, @Data, @Builder, etc.).
Maven modules (pom.xml) are fully supported alongside Gradle modules.
provides, inject (@Inject + @Autowired), annotationscomposables, previewssuspend, flowsxml-usages, resource-usagesdeprecated, suppress, todoextensionsdeeplinksConsult: references/ios-commands.md
storyboard-usagesasset-usagesswiftuiasync-funcs, main-actorpublishersConsult: references/typescript-commands.md
class, interface, type, function, const, decoratorsoutline and imports work with TS/JS filesConsult: references/rust-commands.md
struct, enum, trait, impl, fn, macro_rules!, mod#[test], #[derive])outline and imports work with Rust filesConsult: references/ruby-commands.md
class, module, def, Rails DSLdescribe, it, let), Rails (associations, validations)outline and imports work with Ruby filesConsult: references/csharp-commands.md
class, interface, struct, record, enum, methods, propertiesMonoBehaviour, SerializeField)outline and imports work with C# filesConsult: references/dart-commands.md
class, mixin, extension, extension type, enum, typedef, functions, constructorsoutline and imports work with Dart filesConsult: references/python-commands.md
class, def, async def, decoratorsoutline and imports work with Python filesConsult: references/go-commands.md
package, type struct, type interface, funcoutline and imports work with Go filesclass, case class, object, trait, enum (Scala 3), def, val, var, type, givenextends/with), companion objectsoutline and imports work with Scala filesnamespace, class, interface, trait, enum, function, method, const, property, useextends/implements, namespace importsoutline and imports work with PHP filesConsult: references/perl-commands.md
perl-exportsperl-subsperl-podperl-importsperl-testsConsult: references/module-commands.md
moduledeps, dependentsunused-depsunused-symbolsapiast-index rebuild once in project root to build the indexast-index conventions + ast-index map to understand project structure (~80 lines, ~500 tokens)ast-index map --module <path> to drill down into specific areasast-index search for quick universal search when exploringast-index class for precise class/interface lookupast-index usages to find all references before refactoringast-index implementations to understand inheritanceast-index changed --base main before code reviewast-index update periodically to keep index freshDefault output is human-readable plain text — use it unless you specifically need structured data for scripting.
Add --format json only when:
Supported commands: search, symbol, class, usages, implementations, refs, stats, unused-symbols, map, conventions.
ast-index search "Query" --format json | jq '.results[].path'
For detailed platform-specific commands, consult:
references/android-commands.md - DI, Compose, Coroutines, XMLreferences/ios-commands.md - Storyboard, SwiftUI, Combinereferences/typescript-commands.md - React, Vue, Svelte, NestJS, Angularreferences/rust-commands.md - Structs, traits, impl blocks, macrosreferences/ruby-commands.md - Rails, RSpec, classes, modulesreferences/csharp-commands.md - ASP.NET, Unity, controllers, interfacesreferences/dart-commands.md - Dart/Flutter classes, mixins, extensionsreferences/perl-commands.md - Perl exports, subs, PODreferences/python-commands.md - Python classes, functionsreferences/go-commands.md - Go structs, interfacesreferences/cpp-commands.md - C/C++ classes, JNI functionsreferences/proto-commands.md - Protocol Buffers messages, servicesreferences/wsdl-commands.md - WSDL services, XSD typesreferences/module-commands.md - Module dependencies