defendend/claude-ast-index-search/ast-index

ast-index - Code Search for Multi-Platform Projects

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.

Critical Rules

ALWAYS use ast-index FIRST for any code search task. These rules are mandatory:

1. ast-index is the PRIMARY search tool — use it before grep, ripgrep, or Search tool
2. Pick the command by what you know:

• You have an intent or a description ("how is auth handled", "processing update admin") → ast-index explore "<query>". It ranks by relevance and prints the source.
• You have an exact identifier (UserService, parseConfig) → ast-index search / symbol / class. Add --with-content to symbol when you need its definition body, or to search when the exact qualified name or kind is uncertain.
• search itself falls back to explore ranking when a multi-word query has no literal match, so a wrong pick is not fatal — but explore is the right first call for questions.

1. DO NOT duplicate results — if ast-index found usages/implementations, that IS the complete answer
2. DO NOT run grep "for completeness" after ast-index returns results
3. DO NOT re-read bodies returned by `--with-content` — a successful result replaces the usual sed / awk / grep / rg or file-read step. Use those tools only when the body is truncated or unavailable, or when you need text outside the returned definition.
4. Use grep/Search ONLY when:

• ast-index returns empty results
• Searching for regex patterns (ast-index uses literal match)
• Searching for string literals inside code ("some text") — usages and

refs skip names inside strings and comments

• Searching in comments content

Why: ast-index is 17-69x faster than grep (1-10ms vs 200ms-3s) and returns structured, accurate results.

Prerequisites

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 builds a fresh index and swaps it in; named subtrees and the collected Git history (hotspots --collect) are carried over.

Supported Projects

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.

Minified JavaScript/CSS is never indexed or searched: .js/.mjs/.cjs/.css files named *.min.* or *-min.*, or whose first 64 KiB is minifier output (lines averaging 1000+ bytes of code, not one long string). Grep-based commands skip them too, and outline/imports on such a file print Skipped: minified file instead of parsing it. AST_INDEX_SKIP_MINIFIED=0 turns the filter off.

Core Commands

Explore (one-shot context)

`explore` - Rank the symbols most relevant to a query, show the best files — an outline with line ranges for a type or module (the definitions inside it, the chosen one marked →), the source (read fresh from disk) for a function — list graph neighbours (callers/subclasses), and locate tests by path convention — in a single call. Prefer this over a search + read loop when you want to understand an area; read the slice an outline row points at next. Language-agnostic and vendor-aware (node_modules .d.ts and cross-stack matches are down-ranked, never deleted).

ast-index explore applicant merge MergeService   # bag of symbol/file names
ast-index explore "how does auth session work"   # natural-language question
ast-index explore PaymentService --rwr           # --rwr: re-rank via call/inheritance graph
ast-index explore Repository --max-files 8        # cap source files shown (default 6)
ast-index explore Session request --rwr --format json

• Default (Stage A) ranks by lexical match + multi-term corroboration. The

words of a question are also read run together (pdf to html service finds PdfToHtmlService) and against file paths, so a CamelCase class is found from its words; the type a file is named after ranks above helpers, and statements (has_many :x, scope, include) and namespace-only modules rank below definitions. Question words (how, does, work) are ignored.

• --rwr (Stage B) builds a call/inheritance graph in memory and re-ranks by

personalized PageRank, surfacing callers/subclasses in a "Graph neighbours" section. Slightly slower; best when you care about who-calls-what.

Universal Search

`search` - Perform universal search across files, symbols, and modules simultaneously.

ast-index search "Payment"           # Finds files, classes, functions matching "Payment"
ast-index search "Payment" --with-content  # Include matched symbol bodies
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 "Handler" --with-content  # Include matched symbol bodies
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

Symbols come in tiers: exact name, then a name whose last :: or . segment is the query (Billing::Invoice for Invoice, the schema column users.email for email), then partial matches. Inside each tier definitions come before imports and project code before node_modules; among partial matches test symbols (test files, test_*, TestX) come last.

`search --rank <preset>` - Re-rank the Files and Symbols sections by the file's Git history and the symbol's place in the dependency graph, with a dossier next to every result explaining its position. Use it when the question is not "where is X" but "which of these X":

ast-index search Service --fuzzy --module app/services/ --rank proven  # a settled example to copy
ast-index search Merge --rank risky                   # dangerous to touch: many dependents + unstable history
ast-index search Import --rank hotspots               # keeps being changed and fixed
ast-index search Import --rank hotspots --exclude-tests  # same, spec/test files left out
ast-index search Event --module app/models/ --rank central  # what the rest leans on (PageRank)
ast-index --format json search Merge --rank risky     # rank.applied / rank.missing + per-result dossier

• Relevance stays in charge: the pool is the top 100 project symbols of the

plain order, exact-name matches stay above partial ones, and inside a tier the key is 0.9 × score + 0.1 × 1/(1 + position/20). File path matches use where the match sits (stem, name, directory) as the relevance term.

• History is per file — every symbol in a file shares it ("file history"

in the output). Graph numbers are per symbol; a file result borrows them from its strongest symbol.

• Missing data is never ranked as zeros: the preset is not applied, results

keep plain order, and the output names the command to run (rank.missing[].command in JSON). A stale graph ranks with a warning.

• Third-party code (node_modules, .d.ts) is never scored and is listed

after all project results.

• Formulas were picked by backtesting next-year bugfixes on a 40k-file

monorepo, proven also by hand-judged "which one to copy" queries; the numbers are in USER_GUIDE.md ("Ranking search results"). Safe by the numbers is not the same as a good example: proven cannot tell which of two living styles the team prefers.

File Search

`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 Search

`symbol` - Find symbols (classes, interfaces, functions, properties) by name.

ast-index symbol "PaymentInteractor" # Find exact symbol
ast-index symbol "PaymentInteractor" --with-content  # Include its source body
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 "Mapper" --with-content  # Include bounded source bodies
ast-index symbol "@Service"          # Find all @Service annotations

A namespaced class is found by its short or its full name: LedgerImporter and Billing::LedgerImporter both find class Billing::LedgerImporter (also in class, refs, hierarchy, implementations). An exact short name wins over namespaced ones. usages Billing::LedgerImporter lists references to LedgerImporter on lines that spell out the full name; usages LedgerImporter lists all of them.

Class Search

`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

Usage Search

`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
ast-index usages "parse_config"      # snake_case calls: Python, Rust, Go, C, PHP, ...

Usages (here and in refs) list production files first and test files after them, each group by path and line; in JSON a test reference carries "test": true.

Indexed usages are capitalized names and calls written name(, snake_case and _private names included. Reserved words (sizeof (x), #if defined(X), Go's func (r *T), Python's None) are never recorded.

Performance: ~8ms for indexed symbols.

Cross-References

`refs` - Show cross-references for a symbol: definitions, imports, and usages in one view.