Fast file + content search with code-aware sizing. Replaces Read/Grep/find for routine "where is this file" / "grep for X" / "show me lines 10-20 of Y" questions. Returns file paths + line numbers + a sized chunk, not the whole file. Use when: - "Find files matching <pattern>" / "show me all *.yml under config/" - "Grep for 'TODO' / 'FIXME' / 'TODO\\(perf\\)' / regex anywhere" - "How big is <file>" / "is this file too large to read fully" - "Show me lines 50-80 of <file>" / "read just the relevant slice" - "Find all files matching name + containing string" Replaces: native find + grep + cat invocations (~3-10k tokens for big repos) with single MCP calls (200-500 tokens).
Code archaeology via call graph + symbol resolution. Answer "who calls X", "what does Y call", "where is Z defined", "what's the path from A to B" in one MCP call instead of multi-step grep + read. Uses persisted cross-file resolution (Synapse) so cross-module edges are precise, not regex-guessed. Use when: - User asks "what calls this function" / "what does this function call" - Tracing a bug through layers (impact → caller chain) - Planning refactor of a function/class (need full fanout) - "Where is this symbol defined" / "find all references to X" - "Show me the path from handler → DB" - "Draw a UML class/package/component/sequence diagram" Replaces: grep + read + manual chain-following (~10-30k tokens) with 2-4 MCP calls (~1-3k tokens).
Manage the persistent AST cache / index. Refresh, force-rebuild, inspect cache state, diff one file's AST between commits, advise on parser readiness for a language. Mostly ops/infra, not daily agent work. Use when: - "Re-index the project" / "force rebuild AST cache" - "Why is callees returning unknown" (likely stale index) - "AST diff this file vs last commit" (structural diff, not text diff) - "What language plugins are ready / which are stubs" - Setting up the project for the first time (autoindex) Replaces: manual `rm -rf .ast-cache && reindex` + reading plugin docs.
Build a top-N prioritized refactoring queue by intersecting three signals: health grade (which files are F/D), temporal churn (which files change most often), and dead-code density (which files carry the most unreachable symbols). For each candidate the queue surfaces (a) the dimension that dragged the grade down, (b) the target symbol, (c) blast radius from `nav action=callers`, and (d) a concrete action — `split`, `delete dead`, or `extract`. Motivated by `docs/agent-tooling-gap-report.md` "Next High-Value Work" §5: use `health action=project` output to open focused refactoring slices for the current F-grade files, starting with low-coverage Language Plugin extractors and `api.py`. Use when: - "Where should I refactor next?" / "Build me a refactor queue" - Post-feature cleanup pass - Engineering planning: "what would 2 weeks of cleanup buy us?" - Re-grading after a sprint: "did the queue shrink?" Replaces: per-file `health action=file` loops + spreadsheet ranking (~25k tokens) with 3 parallel MCP calls +
Find "hot zones" — symbols modified often in recent git history that need extra review attention. Adds temporal context (mod_count_30d / 90d / all) to call-graph queries. Like Hebbian "fire-together-wire-together" but for code: functions that change together often deserve scrutiny together. Use when: - User asks "what's churning the most" / "any hot zones?" - Pre-refactor: "what's the history of this function?" - Code review: "is this file getting hammered?" - You see a verdict=CAUTION with "hot zone" in risk_factors Replaces: `git log --follow --stat` + manual counting per-symbol (~10k tokens for non-trivial files) with 1 MCP call (~500 tokens).
Dependency / import graph analysis. Answer "what does this file import", "what imports this module", "what's the project's import topology", "show me the sitemap" without reading every file's import block. Use when: - "What does file X depend on" / "what imports module Y" - "Is module Z a leaf or a hub in the import graph" - "Show me the project sitemap" (which files glue what together) - "Are there circular imports" - Planning a module extraction: who'd you break Replaces: grep-for-import-statements + manual graph walking (~5k tokens for non-trivial repos) with 1 MCP call (~500 tokens).
Pre-edit safety check using tree-sitter-analyzer. One workflow → verdict (SAFE/REVIEW/CAUTION/UNSAFE) + verification command + risk factors → ≤2k tokens, ≤3 MCP calls. Replaces ~10k tokens of grep/read/git-diff exploration before touching a file. Use when: - About to edit a file you haven't touched in this session - Refactoring across multiple files - Asked "is it safe to change X?" or "what breaks if I touch Y?" - Before approving a code review Workflow: 2-3 parallel MCP calls (edit action=safe + edit action=impact + health action=file), fold the verdicts, surface the exact `verification_command` and stop_condition.
The full edit-and-verify loop mandated by CLAUDE.md and docs/agent-tooling-gap-report.md:58. Pre-edit gate (edit action=safe + baseline health action=file) → LLM edits → post-edit verify (health action=file diff + edit action=impact + scoped verification_command). Replaces "edit then run the whole pytest suite" (~5 min) with a scoped verification (~30-60s) that only escalates to full suite when risk remains. Use when: - About to make any non-trivial edit to a code file in tree-sitter-analyzer - User asks "implement X" / "fix this bug" / "refactor Y" / "add this feature" - You just finished editing and need to verify before committing - Any change touching tree_sitter_analyzer/** or tests/** Don't use when: - One-line typo in docs/comments (no behavior change → no verify needed) - Pure README/markdown edits - You're still in plan mode and haven't decided on the edit yet - File you're literally creating from scratch (no callers, no baseline) Workflow: 1 parallel batch pre-edit → edit → 1 parallel batch post-