Tree Sitter Analyzer

🌳 Tree-sitter Analyzer

English | [日本語](READMEja.md) | [简体中文](READMEzh.md)

[](https://pypi.org/project/tree-sitter-analyzer/) [](https://python.org) [](LICENSE) [](https://codecov.io/gh/aimasteracc/tree-sitter-analyzer) [](https://github.com/aimasteracc/tree-sitter-analyzer) [](#supported-agents)

Code intelligence AI agents can trust — correct cross-language structure across 20+ languages, agent-native (MCP + CLI).

TSA indexes your codebase with tree-sitter and serves correct call graphs, symbol search, and structural queries to AI coding agents — locally, with no telemetry.

Why it's different:

• Cross-language correctness is the moat. A name-only index wires Python sorted() to a Swift func sorted. TSA doesn't. ~390× fewer cross-language call-graph mis-wires than alternatives ([reproducible audit](benchmarks/codegraph_compare/MISWIRE-AUDIT-EXAMPLES.md)).
• Built agent-native. 8 MCP tools, TOON output (~half the size of JSON on bulk/tabular responses), verdict envelopes, and 13 curated Skills — designed for Claude Code, Cursor, and any MCP client.
• Broad and correctly classified. 13 languages with full call-graph indexing (Python · Go · Rust · Java · JS · TS · C · C++ · C# · Swift · Kotlin · Ruby · PHP), 8 more symbol-indexed or CLI-reachable.

> Proof: on HuggingFace tokenizers (Rust+Python+JS+TS), a name-only resolver mis-wires 1,259 call edges — TSA: 0. Run it on your repo in seconds: uvx --from tree-sitter-analyzer miswire-audit .

> Upgrading from v1.x? See [docs/MIGRATION.md](docs/MIGRATION.md).

---

Get Started

> Requires Python 3.10+ (check: python3 --version). Install from python.org if needed.

One-line install for Claude Code:

claude mcp add tree-sitter-analyzer \
  --env TREE_SITTER_PROJECT_ROOT="$PWD" \
  -- uvx --from "tree-sitter-analyzer[mcp]" tree-sitter-analyzer-mcp

Restart your agent, then say: "Run the index tool with action=status." CLI equivalent (no agent needed): tree-sitter-analyzer --codegraph-status

> PyPI / uvx users — install skills: the 13 tsa-* skills are bundled in the wheel. Copy them once with: > ``bash > tree-sitter-analyzer --install-skills # into ./.claude/skills/ (this project) > tree-sitter-analyzer --install-skills-global # into ~/.claude/skills/ (all projects) > ` > Git-clone users already have them under .claude/skills/` — no action needed.

[Other agents (Cursor, Copilot, Cline, Continue, Claude Desktop, Roo Code) →](#supported-agents)

Quick install

1. Install dependencies

# uv (required)
curl -LsSf https://astral.sh/uv/install.sh | sh        # macOS / Linux
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

# fd + ripgrep (required for `search action=content` text search; symbol search uses SQLite FTS5 and needs neither)
brew install fd ripgrep                                # macOS
winget install sharkdp.fd BurntSushi.ripgrep.MSVC      # Windows

2. Install Tree-sitter Analyzer

# Standalone install (persistent CLI command):
uv tool install "tree-sitter-analyzer[all,mcp]"
# — or skip installing entirely: the MCP entry below runs via uvx on demand.
# Inside a uv-managed Python project, use: uv add "tree-sitter-analyzer[all,mcp]"

3. Hook it into your agent

See [Supported Agents](#supported-agents). Most clients want this MCP server entry:

{
  "mcpServers": {
    "tree-sitter-analyzer": {
      "command": "uvx",
      "args": ["--from", "tree-sitter-analyzer[mcp]", "tree-sitter-analyzer-mcp"],
      "env": { "TREE_SITTER_PROJECT_ROOT": "/absolute/path/to/your/project" }
    }
  }
}

After restart: "Run the index tool with action=status." CLI equivalent (no agent needed): tree-sitter-analyzer --codegraph-status

See the correctness edge on your own repo — no install, no CodeGraph (it re-indexes first; seconds on a small repo, a minute or two on a large one):

uvx --from tree-sitter-analyzer miswire-audit .

It prints how many call edges a name-only code index (the design most tools use) would mis-wire across a language boundary — e.g. a Python sorted() wired to a Swift func sorted — versus how many TSA does (≈0). On [HuggingFace tokenizers](benchmarks/codegraph_compare/MISWIRE-AUDIT-EXAMPLES.md): 1,259 → 0.

---

Why Tree-sitter Analyzer

• Token-efficient on bulk output. Every MCP response uses TOON, a tabular JSON variant that cuts bulk/tabular payloads by roughly half vs raw JSON ([measured invariant](tests/unit/mcp/testoutputcost_invariants.py)). Note: small metadata-heavy decision-tool responses are currently ~equal-to-larger than JSON under the present envelope wiring — tracked by a strict-xfail invariant and being corrected in [RFC-0018](rfcs/0018-response-envelope-normalization-and-adaptive-toon.md).
• Verdict envelopes. Every response carries verdict: SAFE | CAUTION | UNSAFE | INFO | REVIEW | WARN | ERROR | NOT_FOUND, so orchestrators branch on outcomes without re-prompting.
• Project health grading (A–F). Few code-intel tools expose a whole-project quality grade — TSA grades on size / complexity / coverage / duplication / dependencies / structure / git-hotspots in one call.
• 13 curated workflows (Skills). Pre-baked tool subsets for "find symbol", "trace call chain", "score health", "safe-to-edit before refactor", "PR review", etc.
• 5 layers of safety. edit action=safe + edit action=guard + constraint DSL + edit action=impact + verdict envelopes — designed so agents know before they touch.
• Strict CLI superset of CodeGraph, faster indexing, and a one-call query DSL — with an honest cost comparison ([below](#how-tsa-compares-to-codegraph)).

---

Key Features

Pre-indexed code intelligence (CodeGraph parity + superset)

| Capability | TSA tool | Status | |---|---|---| | Symbol search (FTS5 + BM25 ranked) | search action=symbol | ahead — results sorted by relevance score, not file path | | Go-to-def / find-refs / call hierarchy in one call | nav action=navigate | PRIMARY entry point | | Bulk-fetch N related symbols + relationship map | structure action=explore | parity | | Function-level blast radius + risk score | nav action=impact | parity + risk score | | Who-calls-X / what-X-calls | nav action=callers / action=callees | parity | | Index health at-a-glance (+ edge count) | index action=status | ahead — reports total_edges for graph density signal | | Pre-built call graph cache | index action=auto / action=full / action=sync | parity | | Tests affected by a change (CLI) | --affected FILE... | parity |

Tree-sitter Analyzer exclusive

| Capability | TSA tool | Note | |---|---|---| | BM25-ranked symbol search | all search tools | relevancescore on every result (min-max normalized: best=1.0, weakest=0.0); sort(by='confidence') in DSL | | Semantic search (BM25 pre-filtered) | search action=chain (semantic() DSL) | BM25 pre-filter narrows 40k symbols to ~400 before cosine rerank | | Project A–F health grading | health action=project | 7 dimensions (size/complexity/deps/coverage/duplication/structure/git-hotspot), uncommon among code-intel tools | | TOON output | every tool, output_format: "toon" (default) | ~50 % token saving on bulk/tabular output (decision tools tracked by RFC-0018) | | Verdict envelopes | every tool | SAFE/CAUTION/UNSAFE/INFO/WARN/ERROR/NOT_FOUND | | Safe-to-edit gate | edit action=safe / action=guard | refuses high-risk edits before they happen | | Architectural constraint DSL | edit action=constraints | "module A cannot import B" → enforced | | Code health (file-level) | health action=file | block/long-method/smell detection | | Class hierarchy | structure action=classtree | type-inheritance tree | | Dependency matrix | health action=matrix | module-coupling matrix | | Dead code | health action=dead | transitive unreachable analysis | | Complexity heatmap | health action=heatmap | per-fn cyclomatic + project view | | AST-structural clone detection | viz action=similarity | beyond text similarity | | Mermaid call-graph export | viz action=graph | paste-ready in docs | | UML Mermaid export | viz action=uml | class / package / component / sequence diagrams | | PR review | edit action=pr | AST-diff + semantic classify + blast radius | | agent_summary | every response | next-step hint baked into the envelope | | Synapse cross-file resolver | internal | import-aware, beats regex guessing | | Temporal activation | nav action=lineage | per-symbol git-modification frequency | | One-shot file orientation | project action=smart | health + exports + deps + edit-risk in one call (replaces 3-4 calls) | | Architectural decision journal | project action=journal | persists reasoning across sessions — uncommon among code-intel tools |

Skills (13 curated workflows)

CodeGraph has zero skills. We ship 13 under .claude/skills/tsa-*/:

tsa-landing, tsa-find, tsa-graph, tsa-structure, tsa-deps, tsa-index, tsa-health-watch, tsa-edit-safety, tsa-edit-then-verify, tsa-constraints, tsa-pr-review, tsa-refactor-queue, tsa-temporal.

Each skill ships an allowed-tools subset + procedure recipe + decision-surface schema, so the agent doesn't have to triage 8 tools on every question.

312 CLI flags

Superset of CodeGraph's CLI surface. Highlights:

tree-sitter-analyzer --table full           # method/signature/complexity table
tree-sitter-analyzer --partial-read --start-line N --end-line M 
tree-sitter-analyzer --project-health             # A-F grade across the project
# Note: --callers / --callees require the call-graph index — run --full-index first
tree-sitter-analyzer --full-index                 # build call-graph index (run once)
tree-sitter-analyzer --callers            # who-calls
tree-sitter-analyzer --codegraph-impact       # blast radius + risk
tree-sitter-analyzer --affected          # tests transitively affected
tree-sitter-analyzer --dead-code                  # transitive unreachable
tree-sitter-analyzer --check-constraints          # architectural rules
tree-sitter-analyzer --safe-to-edit         # refuse if risky
tree-sitter-analyzer --uml class                  # Mermaid UML class diagram

Installing the package also registers three standalone search utilities (thin entry points over the same engine, handy in shell pipelines):

list-files           # fd-style file discovery
search-content   # ripgrep-style content search
find-and-grep    # two-stage fd + ripgrep

See [docs/CODEMAPS/cli.md](docs/CODEMAPS/cli.md) for the full surface.

---

How TSA compares to CodeGraph

Call-graph correctness — TSA resolves what CodeGraph mis-wires

Token cost is one axis; a code-intelligence tool's first job is a correct graph.

Head-to-head on this repo, both tools' live indexes (count every call edge whose caller language differs from the callee's — a cross-language mis-wire by construction; [reproducible](benchmarks/codegraph_compare/REPORT-v1.21.0.md)):

| tool | cross-language mis-wires | total call edges | rate | |---|---|---|---| | CodeGraph | 745 | 38,103 | 1.96 % | | Tree-sitter Analyzer | 6 | 114,160 | 0.005 % |

~390× cleaner on cross-language correctness, while resolving 3× more call edges. CodeGraph's mis-wires span 19+ language pairs (python→swift 408, python→typescript 195, python→ruby 81, …); TSA's 6 are all java→python/php from single-word Java method names.

> Don't trust this table — run it on your own repo (no CodeGraph install needed): > ``bash > uvx --from tree-sitter-analyzer miswire-audit . > ` > It indexes your code and prints how many call edges a name-only resolver (the design most indexes use) *would* mis-wire across a language boundary vs how many TSA does — with the offending edges listed (Python sorted() → Swift func at file:line). Add --card for a shareable scorecard. > > **Real runs:** on [HuggingFace tokenizers](benchmarks/codegraph_compare/MISWIRE-AUDIT-EXAMPLES.md) (Rust+Python+JS+TS) a name-only resolver would mis-wire **1,259** call edges (incl. a JS tokenize() → Rust def) — TSA: **0**. On a single-language repo (gin`, Go) both are 0 — no false positives. [More examples →](benchmarks/codegraph_compare/MISWIRE-AUDIT-EXAMPLES.md)

Concretely:

| call (Python _resolve_entry_points / build_response) | CodeGraph | TSA | |---|---|---| | sorted() (Python builtin) | ❌ callee = tests/golden/corpus_swift.swift — a Swift func sorted (wired as a callee of 299 Python functions repo-wide) | ✅ builtin — no cross-language edge | | fts_search() / fts_search_ranked() | ❌ bound to the test mock (FallbackCache) instead of the real method | ✅ resolves to the source method (_ast_cache_query.py / ast_cache.py) |

TSA's per-language resolver gates every binding by language family across 13 languages (Python · Java · Go · JS · TS · C · C++ · Rust · C# · Kotlin · Ruby · PHP · Swift) and demotes test-only definitions for non-test callers, across all of its resolution paths. Telling an agent that a Python function calls a Swift method, or that a production call targets a test mock, is wrong structural data — and it is the dominant failure mode of a name-only index.

Correct and complete — 96.3% of call edges classified

A correct graph that leaves most edges unknown is still half a graph. TSA's resolution cascade now classifies 96.3% of call edges (up from 83.9%), with zero cross-language or test-shadow mis-wires — every gain is gated on the project owning no compatible-language symbol of that name, so shadowing is always preserved:

| resolver tier | what it resolves | source | |---|---|---| | binding cascade | local / self / import / unique-method / single-global | RFC-0002 | | stdlib method names (write_text, strip, items) | str / Path / dict / re / argparse methods → stdlib | [RFC-0004](rfcs/0004-stdlib-method-resolution.md) | | external library methods (raises, given, MagicMock) | pytest / hypothesis / mock → external | [RFC-0005](rfcs/0005-external-method-resolution.md) |

The remaining ~4% unknown is dominated by genuinely-unresolvable dynamic dispatch (BaseTool.execute()), constructors, and ambiguous same-name project methods — the false-positive floor of static analysis, left honest rather than guessed.

> Now multi-language. Cross-language-safe resolution is no longer Python-only. A per-language resolver registry ([RFC-0010](rfcs/0010-resolver-language-registry.md)) gives each language its own classification cascade with conservative stdlib/external tiers, gated by language family so a binding does not cross into an incompatible language. Active classified call graph (call-edge extraction + per-language resolver), 13 languages: Python · Java · Go · JavaScript · TypeScript · C · C++ · Rust · C# · Kotlin · Ruby · PHP · Swift. Each has its own conservative stdlib/external tiers and is adversarially verified to never bind across a language boundary. Swift is notable: CodeGraph's flagship mis-wire binds 299 Python sorted() callers to a Swift func sorted — TSA resolves Swift correctly and refuses that exact cross-language bind (verified both directions). Measured on the active set: 6 cross-language edges (6 of ~57,000 resolved edges, all generic 1-word Java method names) — ~390× cleaner than CodeGraph on cross-language correctness, which wires 299 Python sorted() callers to a single Swift func sorted (TSA binds 0 of 298). Full reproducible audit: [benchmarks/codegraph_compare/REPORT-v1.21.0.md](benchmarks/codegraph_compare/REPORT-v1.21.0.md). Adding a language

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aimasteracc
• Source: aimasteracc/tree-sitter-analyzer
• License: MIT

Install and usage instructions live in the source repository linked above.