From ast-index
Performs structural code searches for symbols, classes, usages, implementations, hierarchies, dependencies, and project maps using ast-index CLI in Kotlin/Java, Swift/ObjC, TypeScript/JS, Rust, Ruby, C#, Dart/Flutter, Scala, PHP, Perl, Python, Go, C++ projects.
npx claudepluginhub defendend/claude-ast-index-searchThis 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.mdPerforms fast structural code searches for symbols, classes, usages, implementations, hierarchies, and dependencies in polyglot projects using ast-index CLI.
Uses tree-sitter index for code navigation in Rust, Python, TypeScript, JavaScript, Go, Java, Scala, SQL: finds symbols, reads function implementations, traces callers, discovers tests.
CLI for Scala 2/3 and Java codebases: find definitions, implementations, usages, imports, members, scaladoc, graphs as ASCII art. Use to explore unfamiliar projects, symbol lookups, test navigation.
Share bugs, ideas, or general feedback.
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