ts-review-graph

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?

Claude Code reads too many files. It grabs large files one after another and stuffs unrelated code into its context.

ts-review-graph pre-builds the project's dependency graph and instantly computes the blast radius (impact surface) of changed files — so Claude only reads what matters.

Real-world benchmark (manako project)

From BENCHMARK.md:

Graph size: 1,191 nodes / 1,400+ edges (Cloudflare Workers monorepo)

Requirements

• Node.js 20+

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, and usage instructions are appended to CLAUDE.md. Restart Claude Code and the MCP server connects automatically.

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).

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

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 is a build artifact — added to .gitignore automatically. Share config.json with your team.

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