Claude-ast-index-search
CLAUDE.md584 starsChanged 6 months agoMITView on GitHub
Fast multi-language code-search CLI written in Rust. Builds a SQLite index of symbols, references, and file paths for ~30 languages via tree-sitter, then answers queries in milliseconds. .claude/rules/*.md is loaded into every Claude Code session automatically — read those for focused guidance (architecture, commands, parsers, commits, testing, release). This file is the starting point. - Language: Rust (edition 2021), MSRV tracks stable. - Parsers: tree-sitter grammars (tree-sitter-<lang> crates) + regex fallbacks for Perl, WSDL/XSD, Vue/Svelte scripts. - Storage: SQLite via…
The file
We split this CLAUDE.md into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 56
No separate linter step — cargo clippy --workspace -- -D warnings before a PR is welcome but not enforced by CI yet.
- Very specific: line 64
--format jsonis per-command: Only commands whose cmd_* signature takes format: &str honour it. - Very specific: line 79
Prefer ? over unwrap/expect in library and command code.
- Distinctive: line 82
No comments that describe WHAT the code does — names should.
- Very specific: line 84
No trailing summaries in commit messages, no Co-Authored-By, no emoji.
- Very specific: line 90
Never use destructive git ops (push --force, tag -d, reset --hard, branch -D) without an explicit ask from the user.
≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ast-index — Contributor Guide for AI Coding Agents
Fast multi-language code-search CLI written in Rust. Builds a SQLite index of symbols, references, and file paths for ~30 languages via tree-sitter, then answers queries in milliseconds.
.claude/rules/*.md is loaded into every Claude Code session automatically —
read those for focused guidance (architecture, commands, parsers, commits,
testing, release). This file is the starting point.
Tech stack
- Language: Rust (edition 2021), MSRV tracks stable.
- Parsers: tree-sitter grammars (
tree-sitter-<lang>crates) + regex fallbacks for Perl, WSDL/XSD, Vue/Svelte scripts. - Storage: SQLite via
rusqlite, cache at~/Library/Caches/ast-index/<hash>/on macOS and$XDG_CACHE_HOME/ast-index/<hash>/on Linux. - CLI:
clapderive with a single global--format {text,json}flag. - Workspace: two crates — root
ast-index(library + binary),crates/ast-index-mcp(MCP server). Default build produces only the root binary; the MCP crate is opt-in viacargo build -p ast-index-mcp.
Folder layout
src/
main.rs # clap CLI + dispatch to commands::*
lib.rs # re-exports db, indexer, parsers, commands
db.rs # SQLite schema, migrations, queries
indexer.rs # filesystem walk + dispatch to parsers + writes
commands/
mod.rs # shared helpers: PathResolver, search_files, relative_path
{index,files,grep,management,modules,analysis,project_info}.rs
{android,ios,perl}.rs # ecosystem-specific commands
parsers/
mod.rs # FileType enum, parse_file_symbols entry point
treesitter/
mod.rs # LanguageParser trait + get_treesitter_parser()
{kotlin,swift,...}.rs # one file per language
queries/<lang>.scm # tree-sitter S-expression queries
{perl,typescript,wsdl}.rs # regex fallbacks
crates/ast-index-mcp/ # MCP server (spawns `ast-index <sub>` per tool call)
tests/ # integration tests, one *_tests.rs file per concern
scripts/bump.sh # version bump — never edit versions by handBuild / test / run
cargo build --release # root binary only (default members)
cargo build --release --workspace # root + MCP
cargo test --release --workspace # full suite, ~600 tests
./target/release/ast-index search FooNo separate linter step — cargo clippy --workspace -- -D warnings before a
PR is welcome but not enforced by CI yet.
Core invariants (break these and things silently rot)
- Paths in the DB are stored relative to whichever root owns the file
(primary project root or an
add-rootextra root). Never store absolute paths; always resolve for display viacommands::PathResolver. --format jsonis per-command. Only commands whosecmd_*signature takesformat: &strhonour it; others print plain text regardless. Don't branch on format in commands that don't accept the arg.- No global
--verbose. Verbose is an explicit per-command flag onrebuildandupdate. Timing output (Time: …,Total time: …) only prints when that flag is set — default output must stay quiet. - stderr vs stdout. Query results, help text, JSON payloads → stdout. Diagnostics, progress, timings, warnings → stderr. MCP captures stdout only; polluting stdout with progress breaks the MCP contract.
- Version bumps go through
./scripts/bump.sh X.Y.Z. It updates 12 files (Cargo.toml, README title+changelog, 3 plugin JSONs, 6 npm package.jsons, marketplace.json). Hand-edits drift.
Code style (the short version)
- Prefer
?overunwrap/expectin library and command code.expectis acceptable only for invariants that are compile-time-provable (regex/query compilation in aLazyLock). - No comments that describe WHAT the code does — names should. Comments explain WHY: a non-obvious invariant, a workaround, a hidden constraint.
- No trailing summaries in commit messages, no
Co-Authored-By, no emoji. One line. See.claude/rules/commits.md. colored::Colorizefor human output only — JSON mode must emit uncolored output (clap setsNO_COLOR-ish behavior implicitly, but don't rely on it; branch onformat == "json"first and return before any coloredprintln!).- Never use destructive git ops (
push --force,tag -d,reset --hard,branch -D) without an explicit ask from the user.
When in doubt
- Adding a command? Read
.claude/rules/commands.md. - Adding a language? Read
.claude/rules/parsers.md. - Writing tests? Read
.claude/rules/testing.md. - Verifying before claiming done? Read
.claude/rules/verify.md. - Committing? Read
.claude/rules/commits.md. - Cutting a release? Read
.claude/rules/release.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

