codegraph

Turn a TypeScript / JavaScript / Vue repository into an explorable knowledge graph — a WebGL viewer for humans, and an MCP server for coding agents.

繁體中文版：README.zh-TW.md

Why

grep answers "where does this string appear". It does not answer "what breaks if I change this", "which files are the risky hubs", or "what is this codebase shaped like". codegraph extracts the structure once and lets both you and your agent query it.

Related MCP server: lsp-intelligence

Features

• Fast AST extraction — no type checker, ~1,600 files in under 5 seconds.

• React + Vue — parses .ts/.tsx/.js/.jsx/.mts/.cts and the <script> blocks of .vue SFCs.

• Real alias resolution — tsconfig/jsconfig paths, solution-style references, and resolve.alias in vite/vue/webpack configs.

• WebGL viewer — force-directed layout in a web worker, type filters, search, neighbour inspection.

• MCP server — six tools that let Claude Code (or any MCP client) query the graph instead of grepping.

Requirements

Node >= 20, pnpm (npm/yarn work too).

Quick start

pnpm install

# 1. extract a repo into web/public/graph.json
pnpm extract /path/to/your/repo

# 2. explore it
pnpm dev            # http://localhost:5173

CLI

pnpm extract <repo-path> [--out <file>] [--exclude dir1,dir2]

Always skipped: node_modules, .git, .next, dist, build, out, coverage, .turbo, .vercel, .output, storybook-static, and all .d.ts files.

Tip: exclude generated code. Indexing a Prisma client adds thousands of Type nodes that drown out everything else — --exclude generated is a common first move.

The graph

Full JSON schema: docs/graph-schema.md.

MCP server

Let a coding agent query the graph:

pnpm mcp                        # serves web/public/graph.json over stdio
pnpm mcp path/to/graph.json     # or an explicit graph

Register it with Claude Code:

claude mcp add codegraph -- pnpm --dir /path/to/codegraph mcp /path/to/graph.json

Parameters and sample output: docs/mcp-tools.md.

Everyday recipes

Concrete things this is actually useful for, in rough order of payoff.

1. Size up a change before you start

You are asked to change a shared util. Is it a 10-minute job or a two-day one?

pnpm extract .
pnpm mcp &   # then ask your agent, or read the numbers yourself

impact on lib/utils.ts at depth 2 returned 191 dependents on a 400-file app. That is the difference between "quick fix" and "needs a plan", and you know it before writing any code.

2. Land in an unfamiliar repo

New job, new client, inherited project. Run the extractor, open the viewer, then call hubs. The top ten files by degree are the ones worth reading first — they are where the codebase's actual decisions live. The folder clusters in the viewer show you the module boundaries nobody documented.

3. Give your coding agent a map

Registered as an MCP server, an agent stops grepping and starts asking. "What calls getCurrentUser?" becomes one node_info call instead of three greps and a guess. This matters most on repos too big to fit in a context window.

claude mcp add codegraph -- pnpm --dir /path/to/codegraph mcp /path/to/graph.json

4. Find dead code before a cleanup sprint

orphans lists files with no incoming imports/renders. Filter out your framework's entry points (route files, config, tests) and what remains is a real deletion candidate list — with the caveat that dynamic imports are invisible, so verify each one.

5. Check whether a design-system component is actually used

renders edges count component usage across JSX and Vue SFCs. Before deprecating <Button>, node_info tells you how many files render it. Before adding a "reusable" component, hubs --type File tells you whether the last three were ever reused.

6. Review a dependency change with your eyes

Extract before and after a refactor, and diff the two graph.json files. Node ids are stable for unchanged code, so the diff is exactly the structural change — new imports, removed calls, a module that quietly gained fifteen dependents.

pnpm extract . --out /tmp/before.json
git switch my-refactor && pnpm extract . --out /tmp/after.json
diff <(jq -S .edges /tmp/before.json) <(jq -S .edges /tmp/after.json)

7. Spot the architecture drifting

Run it monthly and watch the hub list. When a utils.ts climbs from 30 to 95 connections, it has stopped being a utility and become a hidden god-module. Graphs make that visible far earlier than code review does.

Benchmarks

Measured on an M-series Mac, extraction only.

Limitations

Read these before trusting an edge.

• No type checker. Call edges resolve by name: a declaration in the same file, otherwise a name imported into it. Dynamic dispatch, re-exports, and method calls on typed receivers are missed; identically-named symbols can produce a wrong edge.

• Vue templates are not parsed. renders edges for SFCs come from one SFC importing another, so they work with html, pug, or jsx templates — but globally registered components (never imported) are invisible.

• Monorepos are not handled. Only the tsconfig/bundler configs at the repo root are read. Point the extractor at one package at a time.

• No incremental updates. Every run is a full re-parse.

• TS/JS/Vue only. Svelte, Python, Go and friends are not supported.

• The viewer loads the whole JSON. Tens of thousands of nodes render, but ForceAtlas2 needs time to settle and the result is a hairball without clustering.

Roadmap

• Incremental extraction (file hash + watcher)

• Clustering / level-of-detail in the viewer

• Svelte and Astro support

• Optional type-checker-backed resolution for accurate call edges

Contributing

Issues and PRs welcome.

pnpm test            # vitest, 42 tests over fixture repos
npx tsc --noEmit

Tests run the extractor against the small React and Vue fixtures in tests/fixtures/, and drive the MCP server over a real stdio transport. Both must pass before a PR.

License

MIT — see LICENSE.