/ast-index

name: ast-index
description: This skill should be used when the user asks to "find a class", "search for symbol", "find usages", "find implementations", "search codebase", "find file", "class hierarchy", "find callers", "module dependencies", "unused dependencies", "project map", "project conventions", "project structure", "what frameworks", "what architecture", "find Perl subs", "Perl exports", "find Python class", "Go struct", "Go interface", "find React component", "find TypeScript interface", "find Rust struct", "find Ruby class", "find C# controller", "find Dart class", "find Flutter widget", "find mixin", "find Scala trait", "find case class", "find object", "find PHP class", "find Laravel model", "find PHP trait", or needs fast code search in Android/Kotlin/Java, iOS/Swift/ObjC, Dart/Flutter, TypeScript/JavaScript, Rust, Ruby, C#, Scala, PHP, Perl, Python, Go, C++, or Protocol Buffers projects. Also triggered by mentions of "ast-index" CLI tool.
user-invocable: false

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. **DO NOT duplicate results** — if ast-index found usages/implementations, that IS the complete answer 3. **DO NOT run grep "for completeness"** after ast-index returns results 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"`)
• 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 deletes the DB file entirely and creates a fresh index.

Supported Projects

| 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.

Core Commands

Explore (one-shot context)

**`explore`** - Rank the symbols most relevant to a query, print their source (read fresh from disk), 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. 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.
• `--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 "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 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 "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 Search

**`class`** - Find class, inte