ts-review-graph

このプロジェクトは 2026-09-17 にクローズしました。 新規の機能追加・不具合修正・リリースは行いません。 理由: 同一条件の head-to-head ベンチマーク（BENCHMARK.md）で、元となった code-review-graph に対する共変更 recall の優位が確認できなかったため。残る差は pnpm workspace の import 解決だけで、これは code-review-graph の issue #343 を上流で直す方が維持コストが低いと判断した。 代替は code-review-graph を推奨する。npm パッケージは deprecate 済み（0.5.5 が最終版）。

Build a TypeScript dependency graph in SQLite and tell Claude Code (via MCP) the minimal file set to read before any code review, implementation, or debugging session.

日本語: TypeScript プロジェクトの依存グラフを SQLite に構築し、コードレビュー・実装・デバッグ前に「読むべき最小ファイルセット」を Claude Code (MCP) に伝えるツール。

Why?

TypeScript の依存関係には、source の文字列や AST だけではなく、Compiler API と互換性のある module / symbol resolution を通さないと見えないものがあります。例えば non-relative import、型の宣言元、implements / extends の関係です。

ts-review-graph は ts-morph 経由で TypeScript Compiler API の module / symbol resolution を使い、その結果を SQLite graph に保存します。事前構築した graph から変更の blast radius を引くことで、関連度の高いファイルを先に読めます。

co-change ベンチマーク（0.5.5 core・2026-09-16 再測定）

同じ固定 snapshot の3リポジトリ・501 commit で、code-review-graph 2.3.8 本体と比較しました。reverse depth 2 の平均 recall は ts-review-graph 41.55% / code-review-graph 43.60% でした。

code-review-graph の未解決 workspace import は全体 397行 でした。同じ source 223ファイルから ts-review-graph がプロジェクト内へ解決した import は 947エッジです（相対 import 等も含むため、1対1の修復件数ではありません）。型エッジ ablation の全体 recall 差は review +0.00pt、implement +0.00pt でした。

比較の限界: code-review-graph 本体を実行した比較ですが、crg の depth はノード間の CALLS / REFERENCES / TESTED_BY 等を跨ぐため、深さの対応は名目上です。tsconfig の include 外も走査するので、カバレッジの違いも含みます。

製品 baseline は main bc136afdfc47b7f4fcc4e8bcfcbe36ea75ba522f。snapshot・precision 除外・depth 3・改善/悪化件数・再現手順は BENCHMARK.md に記載しています。

Related MCP server: codegraph-mcp

Requirements

• Node.js 20+

• Claude Code plugin を使う場合は bash と sqlite3 CLI

Installation

Single tsconfig

npx @elchika-inc/ts-review-graph@latest install --tsconfig tsconfig.json

Config is saved to .ts-review-graph/config.json, MCP server is registered in .mcp.json (Claude Code) and .codex/config.toml (Codex), and usage instructions are appended to CLAUDE.md. Restart Claude Code and the MCP server connects automatically.

生成される .mcp.json は、MCP server を install に使用した CLI と同じ version に固定します。これにより、セッション起動時に古い graph reader や未確認の将来の latest release が選ばれることを防ぎます。トレードオフとして修正版は自動受信されないため、ts-review-graph の更新時は更新後の CLI version で、初回と同じ --tsconfig / --db option を指定して install を再実行してください。

Monorepo (multiple tsconfigs)

npx @elchika-inc/ts-review-graph@latest install \
  --tsconfig apps/api/tsconfig.json \
  --tsconfig apps/web/tsconfig.app.json \
  --tsconfig apps/worker/tsconfig.json

Multiple tsconfigs are merged into a single unified graph (tested with 1,191+ nodes across layers).

Claude Code plugin（任意）

既存の CLI install はグラフ構築と MCP server 登録を行います。Claude Code plugin はそれに加えて commands・hooks・skills を導入し、Read のたびにブラスト半径をアドバイザリ表示する hook を有効にします。

claude plugin marketplace add elchika-inc/ts-review-graph
claude plugin install ts-review-graph

plugin 自体はグラフを構築しません。plugin 導入前または導入後に、対象 project で CLI の install を別途実行してください。既に config.json がある場合は build でも再構築できますが、plugin は既定の .ts-review-graph/graph.db だけを参照するため、custom --db は使わないでください。

plugin を更新するには claude plugin update ts-review-graph を実行し、Claude Code を再起動します。CLI も更新する場合は、更新後の CLI version で初回と同じ option を指定して install を再実行してください。

Codex

install は Claude Code 用の .mcp.json に加えて、Codex の project 単位設定 .codex/config.toml にも同じ MCP server を登録します。書き込まれる内容は次の形で、version は install に使用した CLI と同じものに固定されます。

[mcp_servers.ts-review-graph]
command = "npx"
args = [
    "-y",
    "@elchika-inc/ts-review-graph-mcp-server@<install に使用した CLI と同じ version>",
]

既に [mcp_servers.ts-review-graph] がある場合はエントリを重複させません。args がある場合、更新できるかは args に @elchika-inc/ts-review-graph-mcp-server の指定があるかで決まります。指定があれば command の値（docker 等）に関わらず、その version 指定だけを差し替えます（version が付いていなければ付与します）。args が無い場合は、command が npx か未指定のときにかぎり既定の args を書き足します。--log-level debug のように独自に足した引数はそのまま残り、command を独自の値へ変えている場合もそれを保持します（command が無いときだけ "npx" を補います）。env は書かず、既存の TS_REVIEW_GRAPH_DB（.mcp.json から写したパスなど）があれば除去します — env の他のキーはそのまま残ります（env が複数行のインラインテーブルの場合は、1行へ畳むとファイルが壊れるため触りません）。他の [mcp_servers.*] エントリや他のセクションには触れません。

次のいずれかに当てはまるエントリは、どう起動したいのかを推測できないためそのエントリだけ更新せず警告します（env も含めて一切変更しません）。install 自体は続行し、.mcp.json などは通常どおり更新されるので、version の更新が必要なら .codex/config.toml を手動で編集してください。

• args に @elchika-inc/ts-review-graph-mcp-server の指定が無い

• args が無く command が npx 以外（command = "docker" など）

• command または args をドット記法（command.foo = ...）やサブテーブル（[mcp_servers.ts-review-graph.command]、その配下も含む）で書いている

• mcp_servers や mcp_servers.ts-review-graph をインラインテーブル・ドット記法（ts-review-graph = { ... } など）で定義している

スキップされた場合、[mcp_servers.ts-review-graph] というテーブル見出しがファイルに無いときは、エントリの新規追加も行いません（末尾に見出しを足すと TOML 仕様違反になる、あるいはどこへ足すべきか決められないため）。上の条件のうち、見出しが無い形で起きるのは次の3つです。

1. mcp_servers = { ... } のように mcp_servers 自体をインラインテーブルで定義している場合。install はインラインテーブルの中身までは解釈しないので、ts-review-graph エントリが既にあるかどうかも判定できません（エントリが無ければ Codex から使えず、既にあっても version は自動更新されません）。→ mcp_servers をテーブル見出し記法（[mcp_servers]）へ書き直してください。

2. [mcp_servers] の下に ts-review-graph = { ... } と書く、または mcp_servers.ts-review-graph.command = "npx" のようにドット記法で書いている場合。→ その定義を [mcp_servers.ts-review-graph] 見出しと、その直下の通常のキーへ書き直してください。

3. [mcp_servers.ts-review-graph] 本体を書かずに [mcp_servers.ts-review-graph.command] / [mcp_servers.ts-review-graph.args]（およびその配下）の子テーブルだけを書いている場合。→ command / args を [mcp_servers.ts-review-graph] 直下の通常のキーへ書き直してください。

いずれも、書き直してから install を再実行するか、[mcp_servers.ts-review-graph] を手動で設定してください。

既存の .codex/config.toml をそもそも正しく読めない場合（値や文字列が閉じていない、括弧の対応が取れていない、テーブル見出しを解釈できない、[mcp_servers.ts-review-graph] セクションやその子テーブル（[mcp_servers.ts-review-graph.env] など）、あるいはその配下のキーが重複定義されている、[[mcp_servers.ts-review-graph]] で定義されている等）、install は .ts-review-graph/config.json・.mcp.json・.codex/config.toml・CLAUDE.md をいずれも書かずに中止します（グラフ構築も行われません）。ただし中止より前に実行される .gitignore の除外設定と .ts-review-graph/ignore の雛形作成は、中止時にも残ることがあります（どちらも冪等です）。表示されたエラーメッセージに従って該当箇所を修正（閉じていない文字列・括弧なら閉じる、重複定義は1つへ統合、[[...]] は通常のテーブル見出しへ）してから install を再実行してください。

既知の制限:

• project 単位の設定が読まれるのは trust 済みの project だけです。 trust されていない project では Codex が .codex/config.toml の mcp_servers を読み込まないため、~/.codex/config.toml へ同じ [mcp_servers.ts-review-graph] を手動で登録してください。trust 状態は ~/.codex/config.toml 側に trust_level = "trusted" として記録されます。

• Codex から使えるのは .codex/config.toml 経由で登録される MCP tools です。 Claude Code plugin が導入する commands・hooks・skills は claude plugin install で Claude Code 側に入るもので、対象 project のディレクトリには置かれないため Codex からは読み込まれません（Codex 自身の hooks / skills 機構とは別物です）。plugin が提供する Read 時のブラスト半径アドバイザリ表示も Codex では働きません。install が使用方法を追記するのは CLAUDE.md なので、Codex のエージェントに恒常的に守らせたい場合は同じ内容を AGENTS.md へコピーしてください。

• Codex 用の書き込みだけを省く option はありません。 install は常に .codex/config.toml を作成・更新します（Codex を使わない project にも作られます）。

• uninstall は .codex/config.toml を自動削除しません（手動削除の案内のみ出します）。

• custom --db を指定した場合でも Codex 用エントリには env を書かないため、Codex 側は既定の .ts-review-graph/graph.db を参照します。エントリが更新対象の場合、.codex/config.toml へ手動で TS_REVIEW_GRAPH_DB を足しても次の install で除去されるため、custom DB を Codex から使う場合は ~/.codex/config.toml 側のエントリか、Codex 起動時の環境変数で指定してください。

Usage

In Claude Code (automatic)

Claude calls get_minimal_context automatically before reading source files:

get_minimal_context(["src/routes/monitors.ts"], "implement")

Example output (implement mode, apps/web + apps/api):

Changed: src/routes/monitors.ts

── Files affected (REVERSE depth=3) ──
  1. src/routes/services.ts   [IMPORTS_FROM]

── Files to change together (FORWARD depth=1) ──
  1. src/env.ts               [direct import]
  2. src/lib/schemas.ts       [direct import]
  3. src/lib/format.ts        [direct import]
  4. packages/db/src/index.ts [direct import]

SKIP: 1170 other files — not in blast radius

CLI commands

MCP tools

Graph health checks

The six graph-query tools (get_minimal_context, get_impact, get_type_usages, get_test_coverage, query_graph, and find_cycles) validate the graph before answering:

ts-review-graph status reports the same verdict on a health: line. MCP graph_status remains quarantine-exempt — it never refuses — and prints the same verdict on its own health: line (OK / MISMATCH (reason) — detail / STALE (n/m files changed), or 判定できません: … when the check itself fails), so the one tool you use to inspect a broken graph does not report "normal" while the other six refuse.

Graph paths are stored relative to the project root, so a graph.db moved or copied with its working tree remains usable at the new root. Because graph.db is ignored, a normal clone or newly created worktree does not contain it and requires install or build.

BFS depth by mode

Configuration

.ts-review-graph/config.json (auto-generated by install, commit to repo):

{
  "tsconfigs": [
    "apps/api/tsconfig.json",
    "apps/web/tsconfig.app.json",
    "apps/monitor-worker/tsconfig.json"
  ]
}

graph.db はビルド成果物です。既定 DB の graph.db・graph.db-wal・graph.db-shm は自動的に .gitignore へ追加されます。--db でリポジトリ内の別パスを指定した場合は、その DB・WAL・SHM を利用者が .gitignore へ追加してください。config.json はチームで共有してください。 Run CLI and MCP commands from the project root. --db changes only the database location; it does not change which directory is treated as the project root.

How it works

Build phase

1. Load each tsconfig.json

2. Walk the AST using the TypeScript Compiler API

3. Extract import/export/type relationships

4. Store nodes and edges in SQLite (graph.db)

Query phase

1. Specify changed files (["src/routes/monitors.ts"])

2. Run BFS in the selected mode:

   • REVERSE: who imports this file (downstream impact)

   • FORWARD: what this file imports (upstream co-change candidates)

3. Return only files within the blast radius

Tech stack

• Language: TypeScript 5.4+

• Database: SQLite 3 (better-sqlite3)

• Graph traversal: SQL recursive CTE (WITH RECURSIVE)

• MCP: Model Context Protocol SDK v1.0.0

• CLI: Commander.js 12.0.0

License

MIT

Packages

Links

• BENCHMARK.md — benchmark data

• CHANGELOG.md — release notes