🌳 Tree-sitter Analyzer

English | 日本語 | 简体中文

AI エージェントが信頼できるコード インテリジェンス — 対応言語一覧全体で正確なクロスランゲージ構造解析、エージェントネイティブ設計（MCP + CLI）。

TSA は tree-sitter でコードベースをインデックスし、コール グラフ・シンボル検索・構造クエリを AI コーディング エージェントへ提供します — 8 MCP ツール + CLI、完全ローカル、テレメトリなし。

なぜ違うのか：

• クロスランゲージ束縛は言語ファミリで門控されます。 名前の一致だけではクロスランゲージの辺は生まれません。これを強制するゲートは規約ではなく実行されるテストです。
• エージェントネイティブ。 8 MCP ツールが構造化 JSON 出力と verdict エンベロープを提供し、CLI とキュレーション済みワークフローからも利用できます。
• 広くかつ正確に分類。 13 言語は pipeline_registered（パイプライン登録済み、非 E2E）です。これは登録・配線の証拠であり、クロスファイル呼び出し解決の検証を意味しません。詳細は生成された対応深度インベントリを参照。

v1.x からの移行は docs/MIGRATION.md を参照。

はじめに

Python 3.10 以上が必要です（確認: python3 --version）。必要に応じて python.org からインストールしてください。

自動インストール（推奨）

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

install.sh は uv の有無を確認して未インストールなら自動導入し、Claude Desktop / Claude Code / Cursor / VS Code の設定ファイルを検出して MCP エントリを自動書き込みします。セットアップ後は tree-sitter-analyzer --doctor で設定を確認できます。

ブートストラップの信頼性について: 利便性のため、上記コマンドは uv が未インストールまたは古い場合、公式 uv インストーラを TLS 経由でダウンロード・実行します。このインストーラは可変であり content-bound ではありません。TSA はダウンロード前に警告を表示し、インストール後に厳密なバージョン確認を行います。この未検証のブートストラップを避けたい場合は、事前に uv >= 0.11.0 を手動でインストールするか、次のセキュアなオプトアウトを使用してください（ブートストラップが必要な場合は手動インストール手順を表示して終了します）:

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

Claude Code へワンライナーでインストール:

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

エージェントを再起動し、こう伝える: 「index ツールを action=status で呼んでください。」 CLI での同等操作 (エージェント不要): tree-sitter-analyzer --codegraph-status

PyPI / uvx ユーザーへ — スキルのインストール: tsa-* スキルはホイールに同梱されています。一度だけ次のコマンドでインストールしてください:

tree-sitter-analyzer --install-skills              # ./.claude/skills/ へ (このプロジェクトのみ)
tree-sitter-analyzer --install-skills-global       # ~/.claude/skills/ へ (全プロジェクト共通)

git clone ユーザーはすでに .claude/skills/ に含まれているため、操作不要です。

その他のエージェント (Cursor / Copilot / Cline / Continue / Claude Desktop / Roo Code) →

クイック インストール

1. 依存関係をインストール

# uv (必須)。この公式簡易インストーラは可変で content-bound ではありません。
# 代替の手動インストール方法は https://docs.astral.sh/uv/ を参照。
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. Tree-sitter Analyzer をインストール

# スタンドアロンインストール(永続 CLI コマンド):
uv tool install "tree-sitter-analyzer[all,mcp]"
# — インストール不要でも可:下の MCP エントリは uvx でオンデマンド実行されます。
# uv 管理の Python プロジェクト内では: uv add "tree-sitter-analyzer[all,mcp]"

3. エージェントへ接続

対応エージェントを参照。多くのクライアントで以下の MCP 設定を使用:

{
  "mcpServers": {
    "tree-sitter-analyzer": {
      "command": "uvx",
      "args": ["--from", "tree-sitter-analyzer[mcp]", "tree-sitter-analyzer-mcp"],
      "env": { "TREE_SITTER_PROJECT_ROOT": "/絶対パス/プロジェクト" }
    }
  }
}

再起動後: 「index ツールを action=status で呼んでください。」 CLI での同等操作 (エージェント不要): tree-sitter-analyzer --codegraph-status

自分のリポジトリでリゾルバの動作を確認（インストール不要、最初に再インデックスします）:

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

クロスランゲージの名前衝突候補を報告し、自分のリポジトリでリゾルバの動作を調査できます。結果は診断情報であり、競合ベンチマークの主張ではありません。

なぜ Tree-sitter Analyzer か

• 構造化出力。 MCP 応答は標準 JSON エンベロープを使用します。ペイロードの挙動はレスポンス契約テストで保護されています。
• Verdict エンベロープ。 すべての応答に verdict: SAFE | CAUTION | UNSAFE | INFO | REVIEW | WARN | ERROR | NOT_FOUND が付き、オーケストレーターは結果に応じて分岐できます。
• プロジェクト健全性 A-F グレーディング。 サイズ、複雑度、カバレッジ、重複、依存、構造、git ホットスポットを組み合わせて評価します。
• キュレーション済みワークフロー（Skills）。 「シンボル検索」「コール チェーン追跡」「健全性評価」「リファクター前の安全チェック」「PR レビュー」などのツール サブセットを提供します。
• 多層的な安全保護。 edit action=safe + edit action=guard + 制約 DSL + edit action=impact + verdict エンベロープで、編集前のリスク判断を支援します。
• CLI/MCP パリティと統合クエリ DSL。 同じ解析プリミティブをエージェントとシェル ユーザーが利用できます。

主要機能

事前インデックス コード インテリジェンス

エージェントのコストは応答の大きさではなくターン数が支配します。追加のツール呼び出しは毎回、会話全体を再送します。TSA は、問いが「もう尋ねなくてよい」と判断できる根拠を応答に載せて返すように作られています。

コード ナビゲーション以外の機能

Skills

TSA は .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。

各 skill は allowed-tools ツール サブセット + 手順レシピ + 決定面スキーマを同梱し、エージェントは 8 個のツールから毎回選別する必要がありません。

354 の CLI フラグ

主なもの:

tree-sitter-analyzer --table full <file>          # メソッド/シグネチャ/複雑度テーブル
tree-sitter-analyzer --partial-read --start-line N --end-line M <file>
tree-sitter-analyzer --project-health             # プロジェクト A-F グレーディング
# 注意: --callers / --callees はコールグラフインデックスが必要 — 先に --full-index を実行
tree-sitter-analyzer --full-index                 # コールグラフインデックスを構築（一度だけ）
tree-sitter-analyzer --callers <symbol>           # 呼び出し元
tree-sitter-analyzer --codegraph-impact <fn>      # blast radius + リスク
tree-sitter-analyzer --affected <file...>         # 影響を受けるテスト
tree-sitter-analyzer --dead-code                  # 推移的到達不能
tree-sitter-analyzer --check-constraints          # アーキテクチャ規則
tree-sitter-analyzer --safe-to-edit <file>        # リスク時に拒否
tree-sitter-analyzer --uml class                  # Mermaid UML class 図

TSA はインデックス検索と有界なライブソース検証をプロセス内で実行します。ripgrep や fd のインストールは不要です。削除された検索ラッパーからの移行は migration guide と CLI codemap を参照してください。

定量的主張のガバナンス

公開するベンチマーク、性能、競合比較の数値は、benchmarks/codegraph_compare/claim_registry.json の provenance-bound registry からのみ生成します。E4 証拠は、ツール名とバージョン、測定値、コーパス、ベンチマーク日付/バージョン、artifact digest を厳密に結び付ける必要があります。E4 未満の証拠は内部情報に留まり、公開文言を生成できません。ベンチマーク runbook を参照してください。

生成項目がない場合、公開が承認された定量的主張は現在ありません。上記の定性的説明は境界を明示した製品能力であり、測定済みの優位性を主張するものではありません。

仕組み

ソース コード → tree-sitter 解析 → SQLite + FTS5 インデックス (.ast-cache/index.db)
                                          ↓
       nav (navigate) / structure (explore) / nav (callers) / ...
                                          ↓
                            JSON レスポンス エンベロープ
                            (verdict + agent_summary + データ)
                                          ↓
                               MCP クライアント / CLI 消費者

8 個のツール（MCP）がインデックス済みクエリと直接的なソース解析を提供します。 索引済みのシンボル/コンテキストクエリの前に、tree-sitter-analyzer --ast-cache --ast-cache-mode index --format json で AST インデックスを明示的に構築してください。ソース変更後は index action=sync でリフレッシュします。索引済みクエリはキャッシュされた AST データを再利用します。自動ウォームアップは個々のツールに固有です。

対応エージェント

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

tree-sitter-analyzer --install-skills              # ./.claude/skills/ へ (このプロジェクトのみ)
tree-sitter-analyzer --install-skills-global       # ~/.claude/skills/ へ (全プロジェクト共通)

{
  "mcpServers": {
    "tree-sitter-analyzer": {
      "command": "uvx",
      "args": ["--from", "tree-sitter-analyzer[mcp]", "tree-sitter-analyzer-mcp"],
      "env": { "TREE_SITTER_PROJECT_ROOT": "/絶対パス/プロジェクト" }
    }
  }
}

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

# 一度だけビルド
docker build -t tree-sitter-analyzer-mcp .

# 現在のリポジトリに対して実行 (サーバーは stdio で MCP を話す; -i は stdin を開いたままにする)
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", "/絶対パス/プロジェクト:/work",
        "-w", "/work",
        "-e", "TREE_SITTER_PROJECT_ROOT=/work",
        "tree-sitter-analyzer-mcp"
      ]
    }
  }
}

⚠️ TREE_SITTER_PROJECT_ROOT は 絶対パス が必須。サーバーは SecurityValidator でエスケープを防ぐセキュリティ境界を強制する。

サポート言語

ランタイムレジストリから生成。22 言語プラグイン; 13 は pipeline_registered（非 E2E）、3 は index_admitted、0 は call_dispatch_only、5 個は data/markup、1 個はスキャフォールド。登録は正のクロスファイル束縛を保証しない。

Lua はインデックス受け入れ済みで call dispatch と resolver slot も持つが、import dispatch とクロスファイル E2E 証拠は未確認。

設定

基本的に設定不要。デフォルトでエージェントに接続して忘れて構わない:

• 出力形式: JSON。明示的に output_format: "json" を指定できます。
• プロジェクト ルート: TREE_SITTER_PROJECT_ROOT (env, MCP) または --project-root (CLI)。
• キャッシュ場所: <project>/.ast-cache/。安全に削除可 — 自動再構築される。
• 任意: TREE_SITTER_OUTPUT_PATH 大出力の書き込み先。

品質とテスト

指標	値
テスト通過	包括的テストスイート ✅
カバレッジ
型安全性	mypy
プラットフォーム	macOS · Linux · Windows（通常操作）。スナップショット証拠は上記のとおりより狭い範囲となる
Pre-commit ゲート	ruff · bandit · mypy · pyupgrade · detect-secrets · tsa-codemap-sync

uv run pytest -q                                # 境界付きのローカル高速ゲート
uv run pytest tests/ -q --timeout=120 -m "not e2e and not network and not benchmark"  # 包括的なローカル スイート
PYTEST_XDIST_AUTO_NUM_WORKERS=1 uv run pytest -q --maxfail=1                  # 高速ゲート、ワーカー1 (CPU負荷を抑える)
PYTEST_XDIST_AUTO_NUM_WORKERS=2 uv run pytest -q --maxfail=1                  # 高速ゲート、ワーカー2 (バランス型)
uv run pytest --lf --maxfail=1                  # 前回失敗したテストだけ再実行
uv run python check_quality.py --new-code-only  # 品質ゲート

トラブルシューティング

開発

git clone https://github.com/aimasteracc/tree-sitter-analyzer.git
cd tree-sitter-analyzer
uv sync --extra all --extra mcp
uv run pytest -q

開発ガイドは docs/CONTRIBUTING.md を参照。

境界と既知の制限

ここに集めたのは、そのまま読むと宣伝文句に見えてしまう範囲の記述です。インストール手順を中断しないよう、この位置にまとめています。

応答サイズとパラメータ名

nav action=navigate は一致したすべての定義の本体を展開し、切り詰めを報告しません。複数のファイルのクラスが共有するシンボル名では、参照集合の全体が同じ応答で返ります。まず search action=symbol で絞り込むか、limit を尊重して truncated を設定する nav action=callers / action=callees を使ってください。

symbol と function_name は callers、callees、impact のいずれでも受け付けられます。navigate と lineage は symbol を要求し、function_name を渡すと verdict エンベロープではなく例外になります。

スナップショット証拠のプラットフォーム範囲

通常のファイル解析、インデックスの作成/更新、レガシー インデックス経由のクエリは、 認証済みスナップショット アクセスとは別物です。既存の Windows 上の操作パスは、 新しいプライベート WAL スナップショット カーネルを必要としません。これらの操作は キャッシュを作成・更新できますが、認証済みの読み取り専用アクセスは別の契約に従います。

このスナップショット実装が追加するのは POSIX 専用のプライベート データベース/WAL 証拠キャプチャであり、 記述子相対操作、O_NOFOLLOW、安全な外部一時ディレクトリ、source/manifest/projection チェックの成功を要求します。これは Windows の読み取り専用スナップショット パリティを提供する ものでも、明示的な access_mode="read_existing" 消費者向けの既存の資格ゲートを拡張するもの でもありません。

Windows のスナップショット認証は develop ベースラインの時点ですでに利用不可であり （SECURE_FD_SNAPSHOT_UNSUPPORTED）、この実装でも引き続き利用できません （WAL_PRIVATE_SNAPSHOT_UNSUPPORTED、completeness="unknown"、スナップショット トークンなし）。 これは物理インデックスが空であることや、通常のクエリが無効化されていることを意味するものでは ありません。新しいキャプチャ パスに対するネイティブ Windows 資格検証は実施されておらず、 ローカルの能力テストはその代替にはなりません。

ファイル単位の certified_at 状態は、完全なスナップショット権限の代替にはなりません。 partial_at の永続履歴は 本 PR では未実装であり、含まれていません。 不完全または検証不能な projection は、認証済み消費者を許可できません。

Pulse / TQL / セマンティック クエリ

これらは nav のアクションと内部 API を支えるサブシステムであり、エージェントが設定するツール面の一部ではありません。制限は推測に委ねず、明示します。

TQL の時間セレクタは変更タイムスタンプを比較するものであり、変更回数を比較するものではありません。 tql_schema アクションは、素の :hot と :recently_modified が共有するウィンドウとデフォルト値を文書化します。深度クエリは正確な定義同一性を保持し、トラバーサル上限を超えた場合は明示的に失敗します。

Pulse のリクエストはスナップショット境界のコンテキストを返します。識別情報・関係性・逆 import コンテキスト・任意のキャッシュ済み LSP エンリッチメントのための SQL 読み取りは、呼び出し元が保有するトランザクションを終了させることなく savepoint を共有します。これは SQL ラウンドトリップやレイテンシの保証を意味するものではありません。

Pulse の Python 逆 import コンテキストは既存のモジュール リゾルバを使用します。これはクロスランゲージのモジュール解決が完全であるという主張ではありません。コメント コンテキストにはコメント抽出込みで再構築されたインデックスが必要です。古いインデックスやコメント抽出に対応していない言語では、空の成功応答ではなく COMMENTS_NOT_INDEXED を返します。不要な場合は、文書化された max_comments 設定でコメント コンテキストを明示的に省略してください。欠落しているレガシー コミット メッセージ投影は遅延リフレッシュのため pending になります。disabled の有効化状態は保持されます。レガシーの NULL 有効化状態も、古いメッセージやカウントをクリアすることなく pending になります。有効化されたキャッシュ済みインデックス作成サイクルは、境界付きの有効化リフレッシュを継続します。Pulse は利用不能な有効化状態を null として公開し、時間的クエリは不完全な有効化証拠を拒否します。リフレッシュは境界付きバッチを通じて実際の Git 履歴を読み取ります。メッセージ読み取りに失敗した場合は、完了したと主張せず保留中の作業として保持します。

セマンティック クエリには既知の保存済み埋め込みモデルと一貫した次元数が必要です。混在または未知のモデルはエラーとなり、プロバイダのフォールバックはありません。オフライン テストではモデル ダブルを使用します。これは実運用プロバイダの品質を保証するものではありません。

Pulse のバッチ処理は成功したエントリを保持しますが、対象のいずれかが失敗すると失敗を報告します。TQL は欠落または読み取り不能なインデックスをエラーとして扱い、これは「マッチなしの準備済みインデックス」とは区別されます。公開リクエストの検証は、インデックスを開いたり埋め込みプロバイダを呼び出したりする前に、無効な型や上限値を拒否します。

貢献とライセンス

• ⭐ GitHub star は他の AI エージェント ユーザーに本ツールを届ける助けに。
• 💖 スポンサー — 継続的な MCP / Skills 開発を支援。
• リード スポンサー: @o93。
• MIT ライセンス — LICENSE を参照。
• リリース履歴: CHANGELOG.md。