ast-index CLI
A Rust CLI that indexes code symbols locally so agents search by structure instead of grep and spend 40-50% fewer tokens.
- 589 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- The CLI reads project sources and writes a local SQLite index, with no network use.
Install
- Works in
Manual install
brew tap defendend/ast-index
brew install ast-indexREADME commands for macOS and Linux. Windows has winget; for others use cargo install ast-index --locked.
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The CLI reads project sources and writes a local SQLite index, with no network use.
This is third-party code. Review the repository files before installing.
What it does
ast-index builds a local SQLite index of symbols, references, imports, modules, dependencies and inheritance, so agents and people move through code by exact structure instead of text matches. `ast-index rebuild` creates the index once, `ast-index update` keeps it current after edits, and `--walk-up` helps in monorepos. Queries go from broad to exact. `explore` answers a topic question such as "payment flow", while `symbol`, `class`, `outline`, `refs`, `usages`, `implementations` and `deps` return definitions, callers, implementations and dependency paths. Optional data is not built on rebuild: `hotspots --collect` ranks files by churn, fixes and author count, `graph build` builds a symbol-to-symbol dependency graph, and `graph dependents` then shows who is hit by a change. More than thirty languages and formats are supported: Kotlin, Java, Swift, TypeScript, JavaScript, Rust, Python, Go, C and C++, C#, PHP, Ruby, BSL for 1C, SQL and others. The author reports measurements on an Android project (about 29 thousand files and 300 thousand symbols): `class` runs in 1 ms against grep's 90 ms and `search` in 11 ms against 280. Claude Code, Codex and Cursor get plugins with a skill, and Claude Code gets an `/initialize` command for first-time setup.
Who it is for. Developers on large multi-language repositories where an agent burns tokens reading whole files and misses with grep, especially in Android, iOS and monorepos.
Good fit when
- An agent looks for who calls a base class method and grep returns hundreds of false matches.
- Before changing a service you need to know which symbols depend on it.
- You must grasp an unfamiliar module by structure and dependencies without reading whole files.
- The repository holds Kotlin, Swift and Python together and search must understand all three.
- You want the most edited and most fixed files fast to see where trouble lives.
Not a fit when
- The repository is small: the index and updates add a step and plain search is enough.
- You need semantic search over the meaning of text and comments: the tool searches code structure.
- The project's language is outside the supported list: only text search remains.
Example request
Build the index with ast-index rebuild and show who uses the PaymentRepository class and what breaks if its interface changes.Limitations
The index has to be refreshed with `ast-index update` after edits and branch switches, or results lag. For frequent edits the author advises a background refresh `ast-index update --background --debounce-ms 500` from a hook.
Git history data and the symbol graph are not built on rebuild and are enabled by separate commands.
Building from source needs Rust, and the resulting binary is about 50 MB. The author took speed measurements on a large Android project, so your numbers will differ.
How to disable. Run `claude plugin uninstall ast-index` and remove the binary with `brew uninstall ast-index` or `cargo uninstall ast-index`. The index lives in the project and is deleted with its folder.
FAQ
How do I install ast-index?
Through Homebrew: `brew tap defendend/ast-index` and `brew install ast-index`. There is also `cargo install ast-index --locked`, `winget install --id defendend.ast-index` and a source build.
How do I connect it to Claude Code?
Run `claude plugin marketplace add defendend/Claude-ast-index-search` and `claude plugin install ast-index`. The plugin adds an `/initialize` command. A `ast-index install-claude-plugin` command also exists.
How do I use it with Codex and Cursor?
For Codex link `plugin/skills/ast-index` to `~/.codex/skills/ast-index` or add the repository as a marketplace. For Cursor link the folder to `~/.cursor/skills/ast-index` or `~/.cursor/plugins/local/ast-index`.
How many tokens does it save?
The author cites 40 to 50% on large repositories by returning structural slices instead of whole files. The figure depends on the project.
What about a monorepo?
If subfolders have their own version-control markers, add `--walk-up` or the `AST_INDEX_WALK_UP=1` variable to reuse the root index.
Discussion
No questions or reviews yet.
Related
CLI toolsLocal code search for Claude Code and Codex: six fast tools in place of grep and Read, with an index that updates itself.
A fast local indexed code search in Rust for AI assistants that plugs into Claude Code, OpenCode and Codex.
Structural code search, lint and rewrite on the syntax tree, with patterns written like ordinary code
A tree-sitter code navigator: a local SQLite index answers an agent about symbols, callers and change impact in milliseconds
codesearch searches code across several repositories with hybrid retrieval and runs fully offline, without a GPU or Docker.
CLI that builds a codebase index and a 250-token map so an agent does not read hundreds of files to find the right one.
README in short
The README lists features and languages, gives a quick example with install and commands, a table of speed measurements against grep and four install methods. Sections on monorepo work and connecting to Claude Code, Codex and Cursor follow.