{"id":35085356,"url":"https://github.com/aimasteracc/tree-sitter-analyzer","last_synced_at":"2026-06-08T01:07:05.540Z","repository":{"id":307258150,"uuid":"1028849208","full_name":"aimasteracc/tree-sitter-analyzer","owner":"aimasteracc","description":"A scalable, multi-language code analysis framework based on Tree-sitter, usable both as a CLI tool and an MCP server.","archived":false,"fork":false,"pushed_at":"2026-03-30T02:16:55.000Z","size":16298,"stargazers_count":27,"open_issues_count":5,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T04:27:09.272Z","etag":null,"topics":["ai","ai-coding","llms","mcp-server","programing","toon","tree-sitter","tree-sitter-analyzer","vibe-coding"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aimasteracc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["aimasteracc"],"tidelift":"pypi/tree-sitter-analyzer"}},"created_at":"2025-07-30T06:42:41.000Z","updated_at":"2026-03-29T14:13:36.000Z","dependencies_parsed_at":"2025-11-12T09:03:23.643Z","dependency_job_id":null,"html_url":"https://github.com/aimasteracc/tree-sitter-analyzer","commit_stats":null,"previous_names":["aimasteracc/tree-sitter-analyzer"],"tags_count":86,"template":false,"template_full_name":null,"purl":"pkg:github/aimasteracc/tree-sitter-analyzer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimasteracc%2Ftree-sitter-analyzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimasteracc%2Ftree-sitter-analyzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimasteracc%2Ftree-sitter-analyzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimasteracc%2Ftree-sitter-analyzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aimasteracc","download_url":"https://codeload.github.com/aimasteracc/tree-sitter-analyzer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aimasteracc%2Ftree-sitter-analyzer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31312744,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-coding","llms","mcp-server","programing","toon","tree-sitter","tree-sitter-analyzer","vibe-coding"],"created_at":"2025-12-27T13:29:16.543Z","updated_at":"2026-06-08T01:07:05.525Z","avatar_url":"https://github.com/aimasteracc.png","language":"Python","funding_links":["https://github.com/sponsors/aimasteracc","https://tidelift.com/funding/github/pypi/tree-sitter-analyzer"],"categories":[],"sub_categories":[],"readme":"# 🌳 Tree-sitter Analyzer\n\n**English** | **[日本語](README_ja.md)** | **[简体中文](README_zh.md)**\n\n\u003e **The MCP code-intelligence server for AI agents — fewer tokens, fewer tool calls, 100 % local.**\n\u003e Pre-indexed AST cache + **8 MCP tools** (down from 63) + 13 curated agent skills + TOON-compressed output.\n\u003e **~80% less tool-definition overhead** vs v1.x — the only code-intel MCP that is both rich-output (verdict + TOON) and Roo/Cursor-safe.\n\u003e A **strict CLI superset** of CodeGraph, with faster indexing, a one-call jQuery-style query DSL, and a **more complete + more correct call graph** (95.9% of call edges classified vs CodeGraph's same-name mis-wires). Token cost was CodeGraph's one edge — RFC-0006 progressive disclosure cut TSA's default context payload **53%**, closing most of that gap. See [How TSA compares](#how-tsa-compares-to-codegraph).\n\u003e **BM25-ranked symbol search** across all 8 facades — results sorted by relevance, not file path.\n\u003e\n\u003e Competing tool count: CodeGraph ~12 · Rhizome 1 · **TSA 8 (rich-output)** · TSA v1.x was 63.\n\u003e Upgrading from v1.x? See [docs/MIGRATION.md](docs/MIGRATION.md).\n\n[![PyPI](https://img.shields.io/pypi/v/tree-sitter-analyzer.svg)](https://pypi.org/project/tree-sitter-analyzer/)\n[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Tests](https://img.shields.io/badge/tests-18427%20passed-brightgreen.svg)](#-quality--testing)\n[![Coverage](https://codecov.io/gh/aimasteracc/tree-sitter-analyzer/branch/main/graph/badge.svg)](https://codecov.io/gh/aimasteracc/tree-sitter-analyzer)\n[![GitHub Stars](https://img.shields.io/github/stars/aimasteracc/tree-sitter-analyzer.svg?style=social)](https://github.com/aimasteracc/tree-sitter-analyzer)\n\n---\n\n## Get Started\n\nOne-line install for **Claude Code**:\n\n```bash\nclaude mcp add tree-sitter-analyzer \\\n  --env TREE_SITTER_PROJECT_ROOT=\"$PWD\" \\\n  -- uvx --from \"tree-sitter-analyzer[mcp]\" tree-sitter-analyzer-mcp\n```\n\nRestart your agent, then say: *\"Set the project root to my repo and run the `index` tool with action=status.\"*\n\n[Other agents (Cursor, Copilot, Cline, Continue, Claude Desktop, Roo Code) →](#-supported-agents)\n\n**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):\n\n```bash\nuvx --from \"git+https://github.com/aimasteracc/tree-sitter-analyzer@develop\" miswire-audit .\n```\n\n_(installs the latest from source until the next PyPI release ships the `miswire-audit` entry point; then `uvx --from tree-sitter-analyzer miswire-audit .`)_\n\nIt 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**.\n\n---\n\n## Why Tree-sitter Analyzer\n\n* **Token-efficient by default.** Every MCP response uses **TOON** — a tabular JSON variant that cuts payload by ~50-70 % vs raw JSON.\n* **Verdict envelopes.** Every response carries `verdict: SAFE | CAUTION | UNSAFE | INFO | WARN | ERROR | NOT_FOUND`, so orchestrators branch on outcomes without re-prompting.\n* **Project health grading (A–F).** No other open-source tool grades your whole project on size / complexity / coverage / duplication / dependencies / structure / git-hotspots in one call.\n* **13 curated workflows (Skills).** Pre-baked tool subsets for \"find symbol\", \"trace call chain\", \"score health\", \"safe-to-edit before refactor\", \"PR review\", etc.\n* **5 layers of safety.** `safe_to_edit` + `modification_guard` + constraint DSL + `change_impact` + verdict envelopes — designed so agents *know* before they touch.\n* **Strict CLI superset of CodeGraph, faster indexing, and a one-call query DSL** — with an honest cost comparison ([below](#how-tsa-compares-to-codegraph)).\n\n---\n\n## How TSA compares to CodeGraph\n\n### Call-graph correctness — TSA resolves what CodeGraph mis-wires\n\nToken cost is one axis; a code-intelligence tool's *first* job is a **correct graph**.\n\n**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)):\n\n| tool | cross-language mis-wires | total call edges | rate |\n|---|---|---|---|\n| CodeGraph | **745** | 38,103 | 1.96 % |\n| **Tree-sitter Analyzer** | **6** | 114,160 | **0.005 %** |\n\n**~390× cleaner on cross-language correctness, while resolving 3× more call edges.** CodeGraph's mis-wires span 17 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.\n\n\u003e **Don't trust this table — run it on your own repo (no CodeGraph install needed):**\n\u003e ```bash\n\u003e uvx --from \"git+https://github.com/aimasteracc/tree-sitter-analyzer@develop\" miswire-audit .\n\u003e ```\n\u003e 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.\n\u003e\n\u003e **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)\n\nConcretely:\n\n| call (Python `_resolve_entry_points` / `build_response`) | CodeGraph | TSA |\n|---|---|---|\n| `sorted()` (Python builtin) | ❌ callee = **`tests/golden/corpus_swift.swift` — a Swift `func sorted`** (wired as a callee of **408** Python functions repo-wide) | ✅ `builtin` — no cross-language edge |\n| `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`) |\n\nTSA'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.\n\n#### Correct *and* complete — 95.9% of call edges classified\n\nA correct graph that leaves most edges `unknown` is still half a graph. TSA's resolution cascade now classifies **95.9%** 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:\n\n| resolver tier | what it resolves | source |\n|---|---|---|\n| binding cascade | local / self / import / unique-method / single-global | RFC-0002 |\n| stdlib **method** names (`write_text`, `strip`, `items`) | `str` / `Path` / `dict` / `re` / `argparse` methods → `stdlib` | [RFC-0004](rfcs/0004-stdlib-method-resolution.md) |\n| external **library** methods (`raises`, `given`, `MagicMock`) | pytest / hypothesis / mock → `external` | [RFC-0005](rfcs/0005-external-method-resolution.md) |\n\nThe 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.\n\n\u003e **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: **~0.01%** cross-language edges (6 of ~57,000 resolved edges, all generic 1-word Java method names) — **~4 orders of magnitude cleaner than CodeGraph**, 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 is one new resolver file (RFC-0010) plus a small call-extraction wiring.\n\n\u003e **Symbol kinds, too.** TSA classifies class members as `kind=method` (20,348 method rows on this repo) — `search action=symbol kind=method` returns them; CodeGraph parity, not a stub. The `index status` payload breaks symbols down by kind and language and edges by kind (`edges_by_kind` — a breakdown CodeGraph does not surface).\n\n### Where TSA leads\n\n- **Index build speed.** Removing a redundant post-index edge-refresh pass cut a cold django index (~2 950 files) from **181 s → 97 s (−46 %)**; the win grows with repo size. Re-index of unchanged files is a content-hash lookup.\n- **Strict CLI superset.** Every MCP tool has a CLI equivalent (CodeGraph's CLI is thinner); *behavioural* defaults (ranking, limits, truncation) are kept in lock-step between the two surfaces. Output format is the one intentional divergence — MCP defaults to TOON (token-efficient for agents), the CLI to JSON (human/`jq`-friendly).\n- **One-call expressiveness.** A jQuery-style chain DSL — `search('X').callees(depth=2).explore(include_code=true).answer(compact=true)` — returns an entire flow's subgraph + source in a single call, with JS-style `true`/`false` so agents can write it naturally.\n- **Output is structured + token-aware.** TOON default for MCP (50–70 % smaller than JSON), per-call truncation hints, consistent test-file de-prioritisation across every ranking path.\n- **Breadth.** Health scoring, safe-to-edit / change-impact gating, 13 curated Skills, and broad language coverage.\n\n### On token cost — and a benchmark we corrected\n\n\u003e **Correction (2026-06).** An earlier version of this section claimed TSA beat CodeGraph on agent token cost (a \"−11 % median\" table). That benchmark had a harness bug: the TSA arm's MCP server was started without an explicit project root and analysed *tree-sitter-analyzer's own source* instead of the target repo, so its numbers were meaningless. The bug is fixed (the harness now passes `--project-root`), the inflated claim is withdrawn, and the honest picture is below.\n\nToken cost was the one axis where CodeGraph led. [RFC-0006](rfcs/0006-context-progressive-disclosure.md) progressive disclosure closes most of the gap at the source: `nav context` now returns a **lean default** — entry points + a compact `related_symbols` list + code blocks — and moves the flat node/edge graph behind an opt-in `include_graph=true`. Measured on this repo (4 representative queries, TOON):\n\n| context payload | chars |\n|---|---|\n| TSA default, before RFC-0006 | ~13,900 |\n| **TSA default, after (lean)** | **~6,600 (−53%)** |\n| TSA `include_graph=true` (full, opt-in) | ~13,900 |\n| CodeGraph baseline | ~4,400 |\n\nThe dominant context call went from **~2.9× CodeGraph's payload to ~1.5×**.\n\nFor context, the per-task `$` cost measured **before** RFC-0006 (corrected harness — Claude Sonnet, gin + django, MCP arms, no errors):\n\n| arm | median cost (pre-RFC-0006) | tool calls | file reads |\n|---|---|---|---|\n| CodeGraph MCP | **~$0.27** | 7 | 2 |\n| Tree-sitter Analyzer MCP | ~$0.42 | 7 | 1 |\n| no-MCP (grep/read) | ~$0.34 | 14 | 7 |\n\nA full per-task `$` re-benchmark is the next measurement (harness command below). We report the payload proxy straight rather than restate the old table as if RFC-0006 hadn't shipped.\n\n### Reactive push + edge-kind breakdown — two things CodeGraph can't do\n\nCodeGraph (and most one-shot indexers) only answer on poll: you ask, it replies with a snapshot, and you re-ask to learn whether anything changed. TSA exposes two capabilities that close that loop:\n\n- **Reactive push / subscription ([RFC-0001](rfcs/0001-reactive-push.md), implemented).** `search action=subscribe` registers a Hyphae selector and returns a `tsa://hyphae/{selector}` MCP resource URI. When the watched code changes, the server emits a resource-updated notification — the agent re-reads the resource instead of polling. `search action=unsubscribe` cancels it. CodeGraph has no push or subscription channel.\n- **`edges_by_kind` in `index action=status`.** Status returns a per-edge-kind count (calls / extends / implements / imports …), not just a single `total_edges` — so an agent can read the graph's shape (how call-heavy vs inheritance-heavy a repo is) before drilling in. CodeGraph surfaces only a flat total.\n\nReproduce the correctness fixes on any repo both tools have indexed:\n\n```bash\n# CodeGraph: emits the cross-language / test-shadow callee\n#   (e.g. `sorted` → corpus_swift.swift, `fts_search` → test mock)\n# TSA after the resolver fix: language-correct, source-preferring\ntree-sitter-analyzer --callees _resolve_entry_points --format json\n```\n\n\u003e Reproduce the cost numbers: `uv run python benchmarks/codegraph_compare/run.py phase full-warm --repos gin,django`. Raw envelopes + the harness fix live in that directory.\n\n---\n\n## Key Features\n\n### Pre-indexed code intelligence (CodeGraph parity + superset)\n\n| Capability | TSA tool | Status |\n|---|---|---|\n| Symbol search (FTS5 + **BM25 ranked**) | `search` action=symbol | **ahead** — results sorted by relevance score, not file path |\n| Go-to-def / find-refs / call hierarchy in one call | `nav` action=navigate | PRIMARY entry point |\n| Bulk-fetch N related symbols + relationship map | `structure` action=explore | parity |\n| Function-level blast radius + risk score | `nav` action=impact | parity + risk score |\n| Who-calls-X / what-X-calls | `nav` action=callers / action=callees | parity |\n| Index health at-a-glance (+ edge count) | `index` action=status | **ahead** — reports `total_edges` for graph density signal |\n| Pre-built call graph cache | `index` action=auto / action=full / action=sync | parity |\n| Tests affected by a change (CLI) | `--affected FILE...` | parity |\n\n### Tree-sitter Analyzer exclusive\n\n| Capability | TSA tool | Note |\n|---|---|---|\n| **BM25-ranked symbol search** | all search tools | relevance_score on every result (min-max normalized: best=1.0, weakest=0.0); sort(by='confidence') in DSL |\n| **Semantic search (133× faster)** | `search` action=chain (`semantic()` DSL) | BM25 pre-filter narrows 40k symbols to ~400 before cosine rerank |\n| **Project A–F health grading** | `health` action=project | 7 dimensions (size/complexity/deps/coverage/duplication/structure/git-hotspot), no competitor offers this |\n| **TOON output** | every tool, `output_format: \"toon\"` (default) | 50-70 % token saving |\n| **Verdict envelopes** | every tool | `SAFE/CAUTION/UNSAFE/INFO/WARN/ERROR/NOT_FOUND` |\n| **Safe-to-edit gate** | `edit` action=safe / action=guard | refuses high-risk edits before they happen |\n| **Architectural constraint DSL** | `edit` action=constraints | \"module A cannot import B\" → enforced |\n| **Code health (file-level)** | `health` action=file | block/long-method/smell detection |\n| **Class hierarchy** | `structure` action=class_tree | type-inheritance tree |\n| **Dependency matrix** | `health` action=matrix | module-coupling matrix |\n| **Dead code** | `health` action=dead | transitive unreachable analysis |\n| **Complexity heatmap** | `health` action=heatmap | per-fn cyclomatic + project view |\n| **AST-structural clone detection** | `viz` action=similarity | beyond text similarity |\n| **Mermaid call-graph export** | `viz` action=graph | paste-ready in docs |\n| **UML Mermaid export** | `viz` action=uml | class / package / component / sequence diagrams |\n| **PR review** | `edit` action=pr | AST-diff + semantic classify + blast radius |\n| **agent_summary** | every response | next-step hint baked into the envelope |\n| **Synapse cross-file resolver** | internal | import-aware, beats regex guessing |\n| **Temporal activation** | `nav` action=lineage | per-symbol git-modification frequency |\n| **One-shot file orientation** | `project` action=smart | health + exports + deps + edit-risk in one call (replaces 3-4 calls) |\n| **Architectural decision journal** | `project` action=journal | persists reasoning across sessions — no competitor exposes this |\n\n### Skills (13 curated workflows)\n\nCodeGraph has zero skills. We ship 13 under `.claude/skills/tsa-*/`:\n\n`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`.\n\nEach skill ships an `allowed-tools` subset + procedure recipe + decision-surface schema, so the agent doesn't have to triage 8 tools on every question.\n\n### 271 CLI flags\n\nStrict superset of CodeGraph's 15-command CLI. Highlights:\n\n```bash\ntree-sitter-analyzer --table full \u003cfile\u003e          # method/signature/complexity table\ntree-sitter-analyzer --partial-read --start-line N --end-line M \u003cfile\u003e\ntree-sitter-analyzer --project-health             # A-F grade across the project\ntree-sitter-analyzer --callers \u003csymbol\u003e           # who-calls\ntree-sitter-analyzer --codegraph-impact \u003cfn\u003e      # blast radius + risk\ntree-sitter-analyzer --affected \u003cfile...\u003e         # tests transitively affected\ntree-sitter-analyzer --dead-code                  # transitive unreachable\ntree-sitter-analyzer --check-constraints          # architectural rules\ntree-sitter-analyzer --safe-to-edit \u003cfile\u003e        # refuse if risky\ntree-sitter-analyzer --uml class                  # Mermaid UML class diagram\n```\n\nSee [`docs/CODEMAPS/cli.md`](docs/CODEMAPS/cli.md) for the full surface.\n\n---\n\n## Quick Start\n\n### 1. Install dependencies\n\n```bash\n# uv (required)\ncurl -LsSf https://astral.sh/uv/install.sh | sh        # macOS / Linux\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"  # Windows\n\n# fd + ripgrep (required for search)\nbrew install fd ripgrep                                # macOS\nwinget install sharkdp.fd BurntSushi.ripgrep.MSVC      # Windows\n```\n\n### 2. Install Tree-sitter Analyzer\n\n```bash\nuv add \"tree-sitter-analyzer[all,mcp]\"\n```\n\n### 3. Hook it into your agent\n\nSee **[Supported Agents](#-supported-agents)**. Most clients want this MCP server entry:\n\n```json\n{\n  \"mcpServers\": {\n    \"tree-sitter-analyzer\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"tree-sitter-analyzer[mcp]\", \"tree-sitter-analyzer-mcp\"],\n      \"env\": { \"TREE_SITTER_PROJECT_ROOT\": \"/absolute/path/to/your/project\" }\n    }\n  }\n}\n```\n\nAfter restart: *\"Set the project root to my repo and call the `index` tool with action=status.\"*\n\n---\n\n## How It Works\n\n```\nSource code → tree-sitter parse → SQLite + FTS5 index (.ast-cache/index.db)\n                                         ↓\n        nav (navigate) / structure (explore) / nav (callers) / ...\n                                         ↓\n                            TOON-compressed envelope\n                            (verdict + agent_summary + data)\n                                         ↓\n                              MCP client / CLI consumer\n```\n\nThe index is built lazily on first query, refreshed on file change via a content-hash diff (`index` action=sync). All 8 tools read from the same `.ast-cache/`, so a query and its follow-up share work.\n\n---\n\n## Supported Agents\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📘 Claude Code\u003c/b\u003e (recommended)\u003c/summary\u003e\n\n```bash\nclaude mcp add tree-sitter-analyzer \\\n  --env TREE_SITTER_PROJECT_ROOT=\"$PWD\" \\\n  -- uvx --from \"tree-sitter-analyzer[mcp]\" tree-sitter-analyzer-mcp\n```\n\nVerify: `claude mcp list`. The 13 `tsa-*` skills auto-discover from `.claude/skills/`.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📗 Claude Desktop\u003c/b\u003e\u003c/summary\u003e\n\nEdit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\\Claude\\`, Linux: `~/.config/Claude/`):\n\n```json\n{\n  \"mcpServers\": {\n    \"tree-sitter-analyzer\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"tree-sitter-analyzer[mcp]\", \"tree-sitter-analyzer-mcp\"],\n      \"env\": { \"TREE_SITTER_PROJECT_ROOT\": \"/absolute/path/to/your/project\" }\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📙 GitHub Copilot (VS Code)\u003c/b\u003e\u003c/summary\u003e\n\nCreate `.vscode/mcp.json` (note: `servers`, not `mcpServers`):\n\n```json\n{\n  \"servers\": {\n    \"tree-sitter-analyzer\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"tree-sitter-analyzer[mcp]\", \"tree-sitter-analyzer-mcp\"],\n      \"env\": { \"TREE_SITTER_PROJECT_ROOT\": \"${workspaceFolder}\" }\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🖱 Cursor / Cline / Continue / Roo Code\u003c/b\u003e\u003c/summary\u003e\n\nAll read the same `mcpServers` schema as Claude Desktop. Cursor: **Settings → MCP**. Cline: MCP panel → Edit settings. Continue: `~/.continue/config.json` under `experimental.modelContextProtocolServers`. Roo Code: MCP panel → Edit MCP Settings.\n\u003c/details\u003e\n\n\u003e ⚠️ `TREE_SITTER_PROJECT_ROOT` must be **absolute**. The server enforces a security boundary against escapes via `SecurityBoundaryManager`.\n\n---\n\n## Supported Languages\n\n21 language plugins; 13 fully wired into the indexer (full symbol + call graph) + 5 (data/markup) reachable via the single-file CLI path + 3 scaffold (plugin exists, indexer wiring pending). The 2026-05-24 patch unblocked Swift / Kotlin / Ruby / PHP / C# that had been silently skipped for months.\n\n| Tier | Languages |\n|---|---|\n| **Full index + symbol + call graph** | Python · Java · JavaScript · TypeScript · Go · Rust · C · C++ · C# · Swift · Kotlin · Ruby · PHP |\n| **Single-file analysis (CLI)** | HTML · CSS · Markdown · SQL · YAML |\n| **Scaffold (plugin exists, indexer wiring pending)** | bash · scala · json |\n\nCodeGraph supports a similar set; the only popular code languages neither tool ships yet are **Dart, Vue, Svelte, Lua** (next-sprint backlog).\n\n---\n\n## Configuration\n\nMostly nothing. The defaults are designed so you can hook it into your agent and forget:\n\n* **Output format**: TOON. Override per-call with `output_format: \"json\"`.\n* **Project root**: `TREE_SITTER_PROJECT_ROOT` (env var, MCP) or `--project-root` (CLI).\n* **Cache location**: `\u003cproject\u003e/.ast-cache/`. Safe to delete — auto-rebuilds.\n* **Optional**: `TREE_SITTER_OUTPUT_PATH` for large-output write target.\n\n---\n\n## Quality \u0026 Testing\n\n| Metric | Value |\n|---|---|\n| Tests passed | 17,456 ✅ |\n| Coverage | [![Coverage](https://codecov.io/gh/aimasteracc/tree-sitter-analyzer/branch/main/graph/badge.svg)](https://codecov.io/gh/aimasteracc/tree-sitter-analyzer) |\n| Type safety | 100 % mypy |\n| Platforms | macOS · Linux · Windows |\n| Pre-commit gates | bandit · mypy · pyupgrade · detect-secrets · codemap-sync · smell-ratchet |\n\n```bash\nuv run pytest -q                                # full suite\nuv run python check_quality.py --new-code-only  # quality gate\n```\n\n---\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---|---|\n| `unsupported language` on `.swift / .kt / .rb / .php / .cs` | Update to ≥ 1.12.x — the 5-language gap was patched in commit `50e99a8f`. |\n| MCP server doesn't appear in client | `TREE_SITTER_PROJECT_ROOT` must be **absolute**; restart the client after config edit. |\n| `database is locked` | Stop any other process holding `.ast-cache/index.db`; if persistent, `rm -rf .ast-cache \u0026\u0026 tree-sitter-analyzer --autoindex`. |\n| Slow first call | First call builds the index. Subsequent calls are sub-second. Run `--full-index` upfront to amortise. |\n| Agent picks the wrong tool | Use a `tsa-*` skill (`/tsa-graph`, `/tsa-find`, ...) — each skill restricts the visible tool set to one workflow. |\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/aimasteracc/tree-sitter-analyzer.git\ncd tree-sitter-analyzer\nuv sync --extra all --extra mcp\nuv run pytest -q\n```\n\nSee **[`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md)** for the development guide.\n\n---\n\n## Contributing \u0026 License\n\n* ⭐ A GitHub star helps surface this tool to other AI-agent users.\n* 💖 [Sponsor](https://github.com/sponsors/aimasteracc) — supports continued MCP / Skills development.\n* Lead sponsor: **[@o93](https://github.com/o93)**.\n* MIT licensed — see [LICENSE](LICENSE).\n* Release history: [CHANGELOG.md](CHANGELOG.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faimasteracc%2Ftree-sitter-analyzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faimasteracc%2Ftree-sitter-analyzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faimasteracc%2Ftree-sitter-analyzer/lists"}