agentleFS
defendenddefendend/Claude-ast-index-search/CLAUDE.md

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
  1. Very specific:

    No separate linter step — cargo clippy --workspace -- -D warnings before a PR is welcome but not enforced by CI yet.

    line 56
  2. Very specific:

    --format json is per-command: Only commands whose cmd_* signature takes format: &str honour it.

    line 64
  3. Very specific:

    Prefer ? over unwrap/expect in library and command code.

    line 79
  4. Distinctive:

    No comments that describe WHAT the code does — names should.

    line 82
  5. Very specific:

    No trailing summaries in commit messages, no Co-Authored-By, no emoji.

    line 84
  6. Very specific:

    Never use destructive git ops (push --force, tag -d, reset --hard, branch -D) without an explicit ask from the user.

    line 90

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

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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: clap derive 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 via cargo 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 hand

Build / 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 Foo

No 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)

  1. Paths in the DB are stored relative to whichever root owns the file (primary project root or an add-root extra root). Never store absolute paths; always resolve for display via commands::PathResolver.
  2. --format json is per-command. Only commands whose cmd_* signature takes format: &str honour it; others print plain text regardless. Don't branch on format in commands that don't accept the arg.
  3. No global --verbose. Verbose is an explicit per-command flag on rebuild and update. Timing output (Time: …, Total time: …) only prints when that flag is set — default output must stay quiet.
  4. 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.
  5. 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 ? over unwrap/expect in library and command code. expect is acceptable only for invariants that are compile-time-provable (regex/query compilation in a LazyLock).
  • 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::Colorize for human output only — JSON mode must emit uncolored output (clap sets NO_COLOR-ish behavior implicitly, but don't rely on it; branch on format == "json" first and return before any colored println!).
  • 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.