tree-sitter-analyzer

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-

Project & file health grading + dead-code detection + watch-daemon for grade drops. Answer "how healthy is this codebase", "what's rotting", "which files need attention", "alert me when something degrades" in one workflow. Use when: - Triaging a codebase: "what should we clean up first?" - Pre-PR check: "did this change make health worse?" - User asks "any dead code?" / "any rotting hot spots?" - Starting long-running session, want auto-alerts on degradation - Project-wide quality reporting Replaces: 5-10 grep/read calls + manual heuristics + spreadsheet (~20k tokens) with 2-3 MCP calls (~2k tokens).

Land in a new (or familiar) codebase using the tree-sitter-analyzer MCP server. One workflow → 6 decision surfaces (project_card / entry_points / recent_signals / health / top_files / agent_next_step) → ≤2k tokens, ≤3 MCP calls. Use when: - First time entering an unfamiliar repository - Returning to a repo after >1 week - User asks "what is this project?" / "where do I start?" Workflow: parallel-fan-out 3-4 MCP tools, fold output, return decision_surface. Replaces the typical 15k-token bootstrap (read README + ls -R + git log + AGENTS).

AST-grounded PR / diff review. One workflow → per-file risk ranking, blast radius per changed symbol, the exact pytest command to gate merge, any architecture-constraint violations, and a final BLOCK / REVIEW / APPROVE verdict — in ~1–2k tokens and 4–6 MCP calls. Goes beyond a generic LLM diff-read because only TSA's `edit action=impact` returns a deterministic `verification_command` + `queue_ledger`, and only the persisted call graph can enumerate true callers/callees of changed symbols. (Per `docs/internal/COMPETITOR_HEAD_TO_HEAD_2026-05-23.md`: CodeGraphContext silently indexes 0 files, grep-ast crashes on Python 3.14, wrale miscounts imports. A pure-LLM diff reader has none of these guard-rails — it cannot reach the AST cache to enumerate callers, cannot consult `architectural-constraints.yml`, and invents a pytest command instead of reading the one TSA computed.) Use when: - Reviewing a local diff (`git diff`, staged, branch-vs-main) - Reviewing a GitHub PR URL - User asks "is this PR safe to merge?" /

Architectural constraint enforcement. Detect forbidden cross-module calls ("MCP must not depend on CLI") at index time and gate edits on them. Rules live in YAML at repo root; violations bubble up through edit action=safe and edit action=impact as UNSAFE verdicts. Use when: - User asks "does this PR break architecture?" - Pre-merge gate: "any forbidden edges?" - User wants to ADD a new architectural rule - You see a verdict=UNSAFE and want to understand why - Onboarding: "what are the architectural rules of this repo?" Replaces: tribal-knowledge architecture reviews + manual import audits (~5-15k tokens) with 1 MCP call (~200 tokens) + a YAML file (the rules).

Structural analysis of one file — classes, methods, exports, common patterns, semantic classification of a diff. Returns the file's *shape* without reading the file body. Use when: - "What classes and methods does X file have" - "Show me a table / outline of <file>" - "Run query: find all decorated functions in file X" - "Is this diff a refactor or a behavior change" (semantic classification) - "Find patterns like singleton / factory in this code" Replaces: reading the whole file (~20k tokens for big files) with structural views (200-1000 tokens).