codegraph 🕸 — Your codebase as a graph, for your eyes and your agent

codegraph parses a TypeScript / JavaScript / Vue repository into a graph of files, symbols, and the edges between them — imports, calls, component usage, inheritance. A WebGL viewer makes the structure visible; an MCP server lets a coding agent query it instead of grepping.

Quick start · Type-aware mode · Monorepos · MCP tools · Recipes · Benchmarks · Graph schema · 繁體中文

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 shape is this codebase". codegraph extracts the structure once, and both you and your agent query it from then on.

On a 400-file app, asking which files matter costs 369 bytes through hubs versus 29.7 KB of file reading — roughly 80× less context for the same answer. Full numbers.

Related MCP server: lsp-intelligence

Install

Node >= 20 and pnpm (npm and yarn work too). Nothing is published to npm yet — clone and run it.

git clone https://github.com/RexHung0302/codegraph.git
cd codegraph
pnpm install

Quick start

# 1. index a repository
pnpm extract /path/to/your/repo

# 2. look at it
pnpm dev            # http://localhost:5173

# 3. or let an agent query it
pnpm mcp

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

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

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

How it fits together

Three independent pieces, one JSON file between them.

• src/extract.ts walks the AST with ts-morph and writes graph.json. The only piece that knows about source languages.

• web/ renders the graph with sigma.js and graphology, ForceAtlas2 running in a worker.

• src/mcp.ts serves the same file over MCP — seven tools, hot-reloading when the graph changes on disk.

Type-aware mode

By default every edge is resolved by name, which is fast and wrong in the corners: a re-export has no declaration to bind to, and repo.name() cannot be told apart from an imported function called name.

pnpm extract <repo> --types runs the same walk with the TypeScript checker turned on. Each identifier is resolved through its symbol first, and the name-based path stays as the fallback, so the mode only ever adds edges — it never drops one the default run found.

Memory is the real cost: the default run frees each file's AST as it goes, and the checker cannot, because a file parsed later resolves symbols back into it. On a repo big enough to matter, run it once with --types for a reference graph and stay on the default for quick re-extractions.

meta.typeAware in graph.json records which mode produced it; graph_stats reports it, and reindex keeps it unless you pass types.

Monorepos

Point the extractor at one package, not at the workspace root. Only the configs at the repo root are read — tsconfig.json, jsconfig.json, referenced project configs, and the bundler config next to them — so from the root of a pnpm/turbo workspace the per-package paths aliases are invisible and imports come out near zero.

pnpm extract apps/web        --out graphs/web.json
pnpm extract packages/ui     --out graphs/ui.json
pnpm mcp graphs/web.json     # one graph per MCP server

Consequences worth knowing before you trust the output:

• Cross-package edges do not exist. import { Button } from '@acme/ui' resolves to a node_modules symlink, which is never indexed — so a package's graph shows it as having no outside dependents. Impact analysis is per package.

• A package's own aliases work as long as its tsconfig.json sits at the path you extracted, which is the normal layout.

• Extracting the workspace root "works" in that it produces a graph — files and folders are all there — but imports, calls and renders collapse. Measured on one pnpm workspace: the root gives 1,610 files and 646 imports; its largest app alone gives 601 files and 1,253 imports. Fewer edges than files on a monorepo is this limitation, not a sparse codebase.

Workspace-wide extraction (reading every package's config and linking @scope/pkg specifiers to the package that declares them) is on the roadmap, not implemented.

MCP server

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

The server reloads whenever the graph file changes on disk, so pnpm extract in another terminal takes effect on the next tool call. Restarting is never required.

Documentation

Limitations

Read these before trusting an edge.

• No type checker unless you ask for one. By default 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. --types fixes the last three; dynamic dispatch stays out of reach.

• Vue templates are not parsed. renders edges for SFCs come from one SFC importing another, which works with html, pug, and jsx templates alike — but globally registered components are invisible.

• Monorepos are not handled. Only the configs at the repo root are read, and cross-package imports resolve into node_modules, which is never indexed. Extract one package at a time — details.

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

Development

pnpm test            # vitest: 52 cases over React, Vue and type-checker fixtures
pnpm exec tsc --noEmit
pnpm build           # production build of the viewer

Tests run the extractor against the miniature repos in tests/fixtures/ and drive the MCP server over a real stdio transport. CI runs both on Node 20 and 22. When you change extraction, add a fixture case rather than adjusting an assertion to match the new output.

Roadmap: incremental extraction, clustering in the viewer, Svelte and Astro support, and workspace-wide extraction for monorepos.

License

MIT — see LICENSE.