tree-sitter-analyzer

🌳 Tree-sitter Analyzer

English | 日本語 | 简体中文 | Español

Code intelligence AI agents can trust — correct cross-language structure across the supported language inventory, 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 bindings are gated by language family. A name match alone does not create a cross-language edge, and the gates that enforce this are executable tests rather than a convention.
• Built agent-native. 8 MCP tools (plus set_project_path) provide structured JSON output and verdict envelopes, with CLI access and curated workflows.
• Broad and correctly classified. The generated support-depth inventory distinguishes pipeline evidence from unverified cross-file behavior.

Upgrading from v1.x? See docs/MIGRATION.md.

Get Started

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

Automated install (recommended)

curl -fsSL https://raw.githubusercontent.com/aimasteracc/tree-sitter-analyzer/main/install.sh | bash

Installs or updates uv >=0.11.0 when needed. For detected clients it configures project-level Claude Code .mcp.json, Cursor .cursor/mcp.json, and VS Code .vscode/mcp.json (servers); it updates an existing global Claude Desktop config and prints a Codex block when Codex is detected. Existing entries are merged with backups. It does not install the CLI. Verify with TREE_SITTER_PROJECT_ROOT="$PWD" uvx --from tree-sitter-analyzer tree-sitter-analyzer --doctor.

Bootstrap trust: for convenience, the command above downloads and executes the official uv installer when uv is missing or outdated. That installer is mutable and not content-bound; TSA warns before downloading it to a temporary file over TLS and performs a strict post-install version check. To avoid this unverified bootstrap, install uv >= 0.11.0 manually first, or use the secure opt-out (which exits with manual-install instructions when bootstrap is needed):

curl -fsSL https://raw.githubusercontent.com/aimasteracc/tree-sitter-analyzer/main/install.sh \
  | TSA_DISABLE_UNVERIFIED_UV_BOOTSTRAP=1 bash

Install command for Claude Code:

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

Build the index once: uvx --from "tree-sitter-analyzer[mcp]" tree-sitter-analyzer --project-root "$PWD" --full-index. Restart your agent, then say: “Run the index tool with action=status.” — expect indexed: true CLI equivalent (no agent needed): uvx --from tree-sitter-analyzer tree-sitter-analyzer --codegraph-status

PyPI / uvx users — install skills: the tsa-* skills are bundled in the wheel. Copy them once with:

uvx --from tree-sitter-analyzer tree-sitter-analyzer --install-skills              # into ./.claude/skills/ (this project)
uvx --from tree-sitter-analyzer 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) →

Quick install

1. Install dependencies

# uv (required). This official convenience installer is mutable/not content-bound;
# see https://docs.astral.sh/uv/ for alternative manual installation methods.
curl -LsSf https://astral.sh/uv/install.sh | sh        # macOS / Linux
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

2. Install Tree-sitter Analyzer

# Standalone install (persistent CLI command):
# [all] = every language grammar + MCP extras (no dev tools)
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. 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" }
    }
  }
}

Build the index once: uvx --from "tree-sitter-analyzer[mcp]" tree-sitter-analyzer --project-root "$PWD" --full-index. After restart: “Run the index tool with action=status.” — expect indexed: true CLI equivalent (no agent needed): uvx --from tree-sitter-analyzer tree-sitter-analyzer --codegraph-status

Check resolver behavior on your own repository — no install required:

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

It reports possible cross-language name collisions so you can inspect resolver behavior on your own repository. Results are diagnostic, not a competitive benchmark claim.

Why Tree-sitter Analyzer

• Structured output. MCP responses use standard JSON envelopes; payload behavior is guarded by response contract tests.
• 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). TSA grades projects across size, complexity, coverage, duplication, dependencies, structure, and git hotspots.
• Curated workflows (Skills). Pre-baked tool subsets for “find symbol”, “trace call chain”, “assess health”, “safe-to-edit before refactor”, “PR review”, etc.
• Layered safety. edit action=safe + edit action=guard + constraint DSL + edit action=impact + verdict envelopes — designed so agents know before they touch.
• Agents and shells share a query surface. The analysis primitives and the unified query DSL are available to both.

Key Features

Pre-indexed code intelligence

An agent’s cost is dominated by turns, not by the size of each reply: every extra tool call re-sends the whole conversation. TSA is built so that a question is answered by a call whose response already carries the evidence needed to stop asking.

Capabilities beyond code navigation

Skills

TSA ships curated workflows 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.

367 CLI flags

Highlights:

tree-sitter-analyzer --table full <file>          # method/signature/complexity table
tree-sitter-analyzer --partial-read --start-line N --end-line M <file>
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 <symbol>           # who-calls
tree-sitter-analyzer --codegraph-impact <fn>      # blast radius + risk
tree-sitter-analyzer --affected <file...>         # tests transitively affected
tree-sitter-analyzer --dead-code                  # transitive unreachable
tree-sitter-analyzer --check-constraints          # architectural rules
tree-sitter-analyzer --safe-to-edit <file>        # refuse if risky
tree-sitter-analyzer --uml class                  # Mermaid UML class diagram

TSA performs indexed code search and live source verification in process. No ripgrep or fd installation is required.

search-content and find-and-grep were removed in version 1.30.0. See the migration guide and CLI codemap.

Quantitative claim governance

Public benchmark, performance, or competitive numbers are emitted only from the provenance-bound registry in benchmarks/codegraph_compare/claim_registry.json. E4 evidence must bind exact tool names and versions, measurements, corpus, benchmark date/version, and an artifact digest. Evidence below E4 remains internal and cannot emit wording. See the benchmark runbook.

The absence of a generated item means that no quantitative public claim is currently authorized. Qualitative descriptions above are bounded product capabilities, not measured superiority claims.

How It Works

Source code → tree-sitter parse → SQLite + FTS5 index (.ast-cache/index.db)
                                         ↓
        nav (navigate) / structure (explore) / nav (callers) / ...
                                         ↓
                            JSON response envelope
                            (verdict + agent_summary + data)
                                         ↓
                              MCP client / CLI consumer

The 8 MCP tools expose indexed queries and direct source analysis (plus set_project_path). Build the AST index explicitly before indexed symbol/context queries with tree-sitter-analyzer --full-index --format json. Refresh it after source changes with index action=sync. Indexed queries reuse cached AST data; automatic warming is specific to individual tools.

Supported Agents

[mcp_servers.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" }

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

{
  "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" }
    }
  }
}

{
  "servers": {
    "tree-sitter-analyzer": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "tree-sitter-analyzer[mcp]", "tree-sitter-analyzer-mcp"],
      "env": { "TREE_SITTER_PROJECT_ROOT": "${workspaceFolder}" }
    }
  }
}

# Build once
docker build -t tree-sitter-analyzer-mcp .

# Run against the current repo (server speaks MCP over stdio; -i keeps stdin open)
docker run --rm -i --user "$(id -u):$(id -g)" \
  -v "$PWD:/work" -w /work tree-sitter-analyzer-mcp

{
  "mcpServers": {
    "tree-sitter-analyzer": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--user", "1000:1000",
        "-v", "/absolute/path/to/your/project:/work",
        "-w", "/work",
        "-e", "TREE_SITTER_PROJECT_ROOT=/work",
        "tree-sitter-analyzer-mcp"
      ]
    }
  }
}

⚠️ TREE_SITTER_PROJECT_ROOT: If set, it must be absolute. If unset, the server uses its working directory. Do not put it in a global (all-projects) config — every project would point at the same repository.

Supported Languages

Generated from runtime registries; see docs/CODEMAPS/languages.md for the full capability matrix. 22 plugins: 13 pipeline-registered, 3 index-admitted, 0 call-dispatch-only, 5 data/markup, 1 scaffold. pipeline_registered is registration evidence, not positive cross-file binding proof. pipeline_registered: C, C++, C#, Go, Java, JavaScript, Kotlin, PHP, Python, Ruby, Rust, Swift, TypeScript | index_admitted: Bash, Lua, Scala | call_dispatch_only: | data_markup: CSS, HTML, Markdown, SQL, YAML | scaffold: JSON

Configuration

Mostly nothing. The defaults are designed so you can hook it into your agent and forget:

• Output format: JSON. The output_format: "json" parameter is retained for explicitness.
• Project root: TREE_SITTER_PROJECT_ROOT (env var, MCP) or --project-root (CLI).
• Cache location: <project>/.ast-cache/. Safe to delete — auto-rebuilds.
• Optional: TREE_SITTER_OUTPUT_PATH for large-output write target.

Quality & Testing

Metric	Value
Test suite	uv run pytest tests/ — the count is whatever the current tree collects; CI owns the signal
Coverage
Type safety	mypy
Platforms	macOS · Linux · Windows for ordinary operations; snapshot evidence has the narrower scope above
Pre-commit gates	ruff · bandit · mypy · pyupgrade · detect-secrets · tsa-codemap-sync

uv run pytest -q                                # bounded local quick gate
uv run pytest tests/ -q --timeout=120 -m "not e2e and not network and not benchmark"  # comprehensive local suite
PYTEST_XDIST_AUTO_NUM_WORKERS=1 uv run pytest -q --maxfail=1                  # quick gate, one worker (lower CPU load)
PYTEST_XDIST_AUTO_NUM_WORKERS=2 uv run pytest -q --maxfail=1                  # quick gate, two workers (balanced)
uv run pytest --lf --maxfail=1                  # rerun only failed tests from last run
uv run python check_quality.py --new-code-only  # quality gate

Troubleshooting

Development

git clone https://github.com/aimasteracc/tree-sitter-analyzer.git
cd tree-sitter-analyzer
uv sync --extra all --extra mcp
uv run pytest -q                                # quick gate (bounded)

See docs/CONTRIBUTING.md for the development guide.

Boundaries and Known Limits

Scope statements that would otherwise read as marketing. They are collected here so the install path above is not interrupted by them.

Response Size And Parameter Names

nav action=navigate inlines the body of every definition it matches and reports no truncation. A symbol name shared by classes in multiple files therefore returns the entire reference set in the same response. Use search action=symbol to disambiguate first, or nav action=callers / action=callees, which honor limit and set truncated.

symbol and function_name are both accepted by callers, callees, and impact. navigate and lineage require symbol; passing function_name to them raises instead of returning a verdict envelope.

Platform Scope Of Snapshot Evidence

Ordinary file analysis, index creation/update, and legacy index-backed queries are separate from certified snapshot access. Their existing Windows operational paths do not require the new private WAL snapshot kernel. They may create or update the cache; certified read-only access has a separate contract.

The snapshot implementation adds POSIX-only private database/WAL evidence capture, requiring descriptor-relative operations, O_NOFOLLOW, a safe external temporary directory, and successful source/manifest/projection checks. It does not deliver Windows read-only snapshot parity or extend the existing qualification gate for explicit access_mode="read_existing" consumers.

Windows snapshot certification was already unavailable in the develop baseline (SECURE_FD_SNAPSHOT_UNSUPPORTED). It remains unavailable in this implementation (WAL_PRIVATE_SNAPSHOT_UNSUPPORTED, completeness="unknown", no snapshot token). This is not a statement that the physical index is empty or that ordinary queries are disabled. Native Windows qualification for the new capture path has not been performed; a local capability test is not a substitute for it.

The per-file certified_at state is not a replacement for full snapshot authority. partial_at persistent history is not implemented. An incomplete or unverifiable projection cannot authorize a certified consumer.

Pulse / TQL / Semantic Query

These subsystems back nav actions and the internal API; they are not part of the tool surface an agent configures. Their limits are stated rather than implied:

TQL temporal selectors compare modification timestamps, not modification counts. The tql_schema action documents the window and the shared default for bare :hot and :recently_modified. Depth queries retain exact definition identity and fail explicitly when traversal limits are exceeded.

Pulse requests return snapshot-bound context. SQL reads for identity, relationships, reverse-import context and optional cached LSP enrichment share a savepoint without ending a caller-owned transaction. This is not a SQL round-trip or latency guarantee.

Pulse’s Python reverse-import context uses the existing module resolver; this is not a claim of complete cross-language module resolution. Comment context requires an index rebuilt with comment extraction. Old indexes and languages without comment extraction return COMMENTS_NOT_INDEXED, rather than an empty success; explicitly omit comment context with the documented max_comments setting when it is not needed. Missing legacy commit-message projections become pending for lazy refresh; disabled activation is preserved. Legacy NULL activation states also become pending, without clearing old messages or counts. Enabled cached indexing cycles continue bounded activation refresh. Pulse exposes unavailable activation as null, while temporal queries reject incomplete activation evidence. Refresh reads real Git history through bounded batches; failed message reads retain pending work rather than claiming completion.

Semantic queries require a known stored embedding model and a consistent dimension. Mixed or unknown models are errors, with no provider fallback. Offline tests use model doubles; they do not certify live-provider quality.

Pulse batches retain successful entries but report failure if a target fails. TQL treats missing or unreadable indexes as errors, distinct from a ready index with no matches. Public request validation rejects invalid types and limits before opening the index or invoking an embedding provider.

Contributing & License

• ⭐ A GitHub star helps surface this tool to other AI-agent users.
• 💖 Sponsor — supports continued MCP / Skills development.
• Lead sponsor: @o93.
• MIT licensed — see LICENSE.
• Release history: CHANGELOG.md.