ast-index

ast-index v3.48.1

Structural, AST-aware code navigation CLI for large, multi-language repositories. It builds a local SQLite index of symbols, references, imports, modules, dependencies, and inheritance so humans and agents can move through code by exact structure instead of grep-style text matches.

https://t.me/defendend_ai_dev

What It Gives You

• Navigate classes, functions, files, imports, usages, callers, implementations, inheritance, modules, and dependency paths.
• Start broad with explore, then jump to exact definitions with symbol, class, outline, and refs.
• Keep the index current with ast-index update after the first rebuild.
• Give coding agents compact, parseable context instead of raw file dumps.
• Save ~40-50% of agent tokens on large repositories by returning structural slices of code instead of whole files.

Languages: Kotlin, Java, Swift, Objective-C, TypeScript, JavaScript, Vue, Svelte, CSS, SCSS, Less, Rust, Zig, C#, Python, Go, C, C++, Scala, PHP, Ruby, Perl, Dart, Protocol Buffers, WSDL, XSD, BSL (1C:Enterprise), Lua, Bash, Elixir, SQL, R, Matlab, Groovy, Common Lisp, GDScript. Project type is auto-detected.

How To

# Install
brew tap defendend/ast-index
brew install ast-index

# Build an index once per project
cd /path/to/project
ast-index rebuild

# Ask code questions
ast-index explore "payment flow"
ast-index search ViewModel
ast-index class BaseFragment
ast-index usages Repository
ast-index implementations Presenter
ast-index deps app

Use ast-index update after edits or branch switches. In monorepos with nested project markers, add --walk-up or AST_INDEX_WALK_UP=1 to reuse the root index.

Guides: User guide for everyday workflow; Command setup guide for install/options/examples.

Performance

Benchmarks on large Android project (~29k files, ~300k symbols):

Command	ast-index	grep	Speedup
imports	0.3ms	90ms	260x
dependents	2ms	100ms	100x
deps	3ms	90ms	90x
class	1ms	90ms	90x
search	11ms	280ms	14x
usages	8ms	90ms	12x

Installation

Homebrew (macOS/Linux)

brew tap defendend/ast-index
brew install ast-index

Winget (Windows)

winget install --id defendend.ast-index

Migration from kotlin-index

If you have the old kotlin-index installed:

brew uninstall kotlin-index
brew untap defendend/kotlin-index
brew tap defendend/ast-index
brew install ast-index

From source

git clone https://github.com/defendend/Claude-ast-index-search.git
cd Claude-ast-index-search
cargo build --release
# Binary: target/release/ast-index (~44 MB)

Troubleshooting: Syntax errors on install

If brew install ast-index fails with merge conflict errors (<<<<<<< HEAD), reset your local tap:

cd /opt/homebrew/Library/Taps/defendend/homebrew-ast-index
git fetch origin
git reset --hard origin/main
brew install ast-index

Monorepo Workflow

If your repo has subdirectories with their own VCS markers (git submodules, subtrees, nested Cargo.toml / settings.gradle), read-commands normally stop at the nearest marker — they won't reuse a parent-level index even if one exists. Pass --walk-up, or set AST_INDEX_WALK_UP=1, to tell the lookup to prefer any existing parent DB over nested markers:

# once, in the root
cd /monorepo && ast-index rebuild

# later, from any subproject — reuse the root index
AST_INDEX_WALK_UP=1 ast-index search ViewModel
# or per-call:
ast-index --walk-up search ViewModel

This is opt-in by design: silently preferring a far-away parent DB could surface a stale or misconfigured index from an earlier accidental rebuild higher up. With the flag you explicitly say "trust the parent".

AI Agent Integration

Claude Code Plugin

# Option 1: via marketplace
claude plugin marketplace add defendend/Claude-ast-index-search
claude plugin install ast-index

# Option 2: if ast-index is already installed
ast-index install-claude-plugin

Restart Claude Code to activate. Update: brew upgrade ast-index && claude plugin update ast-index. Uninstall: claude plugin uninstall ast-index.

The Claude plugin ships /initialize as the default setup command. It auto-detects project stack(s), including KMP and polyglot repos, then writes .claude/settings.json and .claude/rules/ast-index.md. Use /initialize-android, /initialize-ios, /initialize-web, /initialize-rust, /initialize-csharp, or /initialize-ruby only as manual overrides.

See examples/.claude/rules/ast-index.md for a template rules file that teaches the agent to use ast-index for structural navigation, outline before reading large files, and pass the same instructions to subagents. Adapt before dropping into your project's .claude/rules/.