claude-graph

A local knowledge graph for Claude Code — structural code intelligence with zero network calls.

Answer structural questions about your codebase in a single MCP tool call — without sending a single byte of code to the cloud.

Why claude-graph?

Claude Code answers structural questions ("what calls this?", "what breaks if I change this file?") by reading source files into context. On any non-trivial codebase that means:

• Hundreds of files that may not fit in the context window

• Thousands of tokens spent on code Claude won't actually use

• No answer at all for repos larger than the context window

claude-graph solves this by building a persistent call graph (functions → calls → functions, files → imports → files, tests → tests_for → source) stored in a local SQLite database. Claude issues a single MCP tool call and gets back only the relevant nodes and edges — typically 7× to 236× fewer tokens than reading the source files directly.

Everything happens on your machine. No embeddings, no cloud API, no telemetry — ever.

Related MCP server: better-code-review-graph

Real benchmark — Django (3,040 files)

Built with claude-graph build on a shallow clone of Django main.

Build time:  17 seconds
Files:       3,040
Nodes:       45,096   (functions + classes + modules)
Edges:       938,763  (calls + imports + tests_for)

Dumping the full Django source naively = 1,475,429 tokens — 7.4× Claude's 200k context window. Claude cannot answer structural questions about Django at all without a tool like this.

Quick start

# 1. Install
pip install claude-graph

# 2. Wire it into your project (writes .mcp.json + .claude/skills/)
cd /path/to/your/project
claude-graph install

# 3. Build the graph
claude-graph build

Restart Claude Code (or run /mcp to confirm claude-graph is connected), then ask:

"What calls save() in this repo?" "What breaks if I change auth/middleware.py?" "Is parse_file covered by tests?"

Features

🔍 Structural queries

Ask Claude things it couldn't answer without reading the entire repo:

📡 Impact radius

Changed a file? Get the blast radius instantly:

claude-graph query callers_of parse_file
# or let Claude Code call get_impact_radius_tool automatically

🗺️ Interactive visualization

claude-graph viz                        # whole graph (capped at 500 nodes)
claude-graph viz --symbol HttpResponse  # direct neighborhood of a symbol
claude-graph viz --impact db/models.py  # visual blast radius of a file
claude-graph viz --max-nodes 0          # uncapped (may be slow on large repos)

The viz renders a self-contained HTML file — no server, works fully offline. Features:

• Force-directed D3 layout with drag, zoom, and pan

• Click any node to highlight its direct neighborhood + see file/line

• Filter panel to toggle node kinds (function / class / module) and edge kinds (calls / imports / tests_for) live

• Translucent file-cluster hulls grouping nodes that share a file

• Search box to find any node by name

👁️ File watcher

pip install "claude-graph[watch]"
claude-graph watch   # auto-rebuilds incrementally on every file change

🩺 Health check

claude-graph doctor

Verifies grammars, FTS5, git access, MCP wiring, and graph existence — with a pass/fail table and exit code.

Zero network calls

Built for corporate and regulated environments with one hard requirement: everything stays on your machine.

• No embeddings, no vector index, no model downloads

• No cloud API calls — not even for tokenization

• No telemetry, no daemon, no background process

• No home-directory writes — everything lives inside your repo (.claude-graph/, .mcp.json, .claude/skills/)

• Nothing runs automatically — you or Claude Code call build_or_update_graph explicitly

See tests/test_no_network.py for the automated proof: a full build + query + viz + MCP startup cycle with outbound sockets disabled.

MCP tools (used by Claude Code automatically)

CLI reference

Every command accepts --repo PATH to target a repo other than $CWD.
status, install, viz, doctor, query, and search accept --json.

Supported languages

31 built in. Powered by tree-sitter-language-pack which bundles 306 grammars — add any of them with a single .claude-graph/languages.toml entry, no code change needed.

Adding a language: drop a .claude-graph/languages.toml into your repo. See claude_graph/default_languages.toml for the schema (extensions, grammar name, node types for functions/classes/imports/calls).

Install options

pip (recommended)

pip install claude-graph

# With file-watching support
pip install "claude-graph[watch]"

Docker

docker pull ghcr.io/mohansagark/claude-graph:latest
docker run --rm -v "$PWD:/repo" ghcr.io/mohansagark/claude-graph build
docker run --rm -v "$PWD:/repo" ghcr.io/mohansagark/claude-graph viz --symbol MyClass

From source

git clone https://github.com/mohansagark/claude-graph.git
cd claude-graph
pip install -e .

From a release asset (no PyPI)

Each GitHub Release ships a wheel as a downloadable asset:

pip install https://github.com/mohansagark/claude-graph/releases/download/v0.2.3/claude_graph-0.2.3-py3-none-any.whl

Requirements

• Python 3.11+

• git

• macOS, Linux, or Windows

How call resolution works

• A calls edge's source is always a function-kind node — only functions/methods make calls.

• A calls edge's target prefers a function match; if none exists, falls back to a class match (instantiation, e.g. Foo()).

• One edge per call site — if bar() is called twice, you get two edges. Call frequency is preserved.

• Cross-file resolution is name-based: a call to save() matches every function named save in the graph. This is a deliberate precision/recall trade-off — better to surface too many candidates for Claude to disambiguate than to miss a real caller.

Known limitations

• Name-based call resolution — cross-file calls match by name only, not by scope. Highly common names (save, get, run) produce over-broad results on large repos.

• tests_for linking — naming convention + imports only (test_foo.py ↔ foo.py, foo.spec.ts ↔ foo.ts). Tests that don't follow a convention aren't linked.

• Import resolution — best-effort path matching, not real module resolution. Won't follow tsconfig.json path aliases or Python namespace packages.

• Incremental edge re-linking — claude-graph update only re-links edges for changed files. Moving a symbol to another file keeps stale cross-file edges until the next full claude-graph build.

Contributing

git clone https://github.com/mohansagark/claude-graph.git
cd claude-graph
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

Releasing (maintainers)

Bump version in pyproject.toml, then cut a GitHub Release. Publishing the release triggers .github/workflows/publish.yml which uploads to PyPI via OIDC trusted publishing and pushes the Docker image to GHCR — no API tokens stored in this repo.

License

MIT © Mohansagar Killamsetty