CodeGraph — give your coding agent a local repo brain

Build a 100% local symbol knowledge graph for any large codebase and wire it into Claude Code / Cursor / Codex CLI over MCP. With it, an agent that used to answer "where does this request get handled?" / "who calls this?" / "what does changing this touch?" with a fan-out of Glob + Read + Grep now answers in one codegraph_* MCP tool call. Output: a shareable before/after report where tool calls, context tokens, and turn time all drop measurably.

The underlying tool is the open-source MIT CLI @colbymchenry/codegraph (npm). The graph is a local SQLite + FTS5 file under .codegraph/codegraph.db. No data leaves your machine. No API keys. No Clawvard backend. No private repo required.

Supports 20+ languages out of the box (TS/JS/Python/Go/Rust/Java/C#/PHP/Ruby/C/C++/ObjC/Swift/Kotlin/Scala/Dart/Svelte/Vue/Liquid/Pascal/Lua/Luau).

1. Prerequisites

• Node ≥ 18 (for npx @colbymchenry/codegraph).
• Any agent with MCP support — Claude Code / Cursor / Codex CLI / opencode — already logged in.
• About 200–500 MB free disk for the .codegraph/ index, depending on repo size.
• Zero commercial API key required. Zero Clawvard credits consumed. No private repo (including clawvard) needed.

2. Install & index — one shot per repo

You don't need a global install. npx runs the bundled CLI.

cd /path/to/your/repo

# Initialize + run the first index in one step
npx @colbymchenry/codegraph init --index
# => writes .codegraph/codegraph.db (SQLite) — node + edge tables, FTS5 search

# Sanity-check size + node breakdown (no API key, fully local)
npx @colbymchenry/codegraph status
# => Files / Nodes / Edges / DB Size / Nodes by Kind / Files by Language

If you re-index later, npx @colbymchenry/codegraph index --force rebuilds; sync only picks up diffs since the last index. The shipped daemon also auto-syncs on file changes once serve --mcp is attached.

3. Wire it into your agent over MCP — one config block

The MCP server is just codegraph serve --mcp over stdio. For Claude Code, add this to ~/.claude.json (merging with whatever you already have):

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@colbymchenry/codegraph", "serve", "--mcp"]
    }
  }
}

If you prefer the CLI to do this for you, the upstream tool ships npx @colbymchenry/codegraph install (auto-detects Claude Code / Cursor / Codex / opencode and writes the right config).

Restart your agent. The MCP server registers 5 tools in the agent's tool list:

The same CLI also exposes callers, callees, impact, affected, query, files, context, status as plain subcommands — handy for shell / CI scripts even when MCP isn't attached.

4. The agent prompts that actually pay off

Once the MCP server is up, the agent's best move is to start every "how does X work?" / "who calls X?" / "what breaks if I change X?" question with codegraph_context or codegraph_node, not with Glob/Grep. The instructions block the MCP server registers (see codegraph serve --mcp output) tells the agent exactly that.

A good operating loop:

1. Onboard a repo → codegraph_context "What does this repo do? Three most important modules, three outward-facing entry points."
2. Find an entry point → codegraph_context "How does an incoming HTTP request get handled?" (returns the right symbols + the right snippets, no file browsing required).
3. Find callers / callees of a symbol → codegraph_node send — the response includes a "Called by ← / Calls →" trail you can follow without Read.
4. Estimate blast radius of a refactor → codegraph_context "If I change Response.send's signature, what code paths and call sites are affected?" — returns the entry symbol + related symbols grouped by file. For a more surgical answer, drop to the CLI: codegraph impact <symbol>.
5. Trace a flow → codegraph_trace from=<symbol> to=<symbol> — one call returns the call chain with each hop's body inlined.

The agent should trust the codegraph result rather than re-verifying it with Grep. The graph is a real AST parse; grep is a substring match and will under- or over-count.

5. The before/after report — the deliverable

The course's headline deliverable is codegraph-before-after.html: a single-file, self-contained HTML report that shows your agent's measured behaviour before vs. after codegraph is wired in, on the same three tasks, on the same repo. It's the artifact you screenshot and share.

Reproduce it on the course's baseline repo:

# 1) Get the baseline repo at the pinned commit
git clone https://github.com/expressjs/express.git
cd express
git checkout dae209ae6559    # pinned commit (master @ 2026-05-17)

# 2) Index it (≈1 s on this repo size)
npx @colbymchenry/codegraph init --index
npx @colbymchenry/codegraph status
# => 141 JS files · 990 nodes · 810 edges · 1.14 MB SQLite

# 3) Run the three head-to-head tasks
# ── T1: HTTP request entry points
#   BEFORE (naïve): Glob lib/**/*.js → Read lib/express.js / application.js / request.js / response.js → Grep "handle("
#   AFTER:          codegraph_context "Which file and function handles incoming HTTP requests? 3 most important entry points."
#
# ── T2: who calls Response.send
#   BEFORE: Grep "\.send(" → Read lib/response.js → Grep "this.send(" → Grep "res.send("
#   AFTER:  codegraph_node send
#
# ── T3: blast radius of changing Response.send
#   BEFORE: Glob lib/** → Read lib/response.js → Grep "\.send(" → Grep "send\." → Read test/res.send.js
#   AFTER:  codegraph_context "If I change Response.send's signature, what code paths and call sites are affected?"
#           (or, on the CLI: codegraph impact send)

For each task, record three indicators on each side: tool calls (count), context tokens (Claude Code /cost prompt + completion, or bytes ÷ 4 as a deterministic substitute), and wall-clock turn time. Render them into codegraph-before-after.html:

• top: three side-by-side cards (Tool calls / Context tokens / Wall-clock) with before, after, and the drop %;
• middle: one collapsible block per task with the before and after tool-call trace;
• bottom: a one-line conclusion and a https://clawvard.school/courses/codegraph CTA.

On expressjs/express @ dae209ae6559 the course's reference report measures 15 → 3 tool calls (−80%), 29,812 → 414 context tokens (−98.6%) and 60.0 s → 14.8 s turn time (−75%). The reference HTML — and the raw before/after logs that produced those numbers (t1_before.log … t3_after.log) — live next to this SKILL.md under public/skills/codegraph/.

6. Troubleshooting

• codegraph: command not found — you skipped the npx -y prefix. Use npx -y @colbymchenry/codegraph …, or npm install -g @colbymchenry/codegraph if you want a global codegraph bin.
• MCP tools don't appear in Claude Code — your config file is ~/.claude.json (not ~/.config/claude/...); make sure you restarted the agent after editing it. npx @colbymchenry/codegraph install --agent claude-code will write the entry for you.
• "This project is not initialized" — .codegraph/ doesn't exist yet; run npx @colbymchenry/codegraph init --index.
• Index looks stale after big edits — npx @colbymchenry/codegraph sync; the file watcher should keep up automatically once serve --mcp is attached.
• WSL2 / network mount feels slow — start the server with npx @colbymchenry/codegraph serve --mcp --no-watch to disable the file watcher; re-sync manually.
• Stale lock (.codegraph/lock) — npx @colbymchenry/codegraph unlock.

7. You will walk away with

• .codegraph/codegraph.db — the local SQLite knowledge graph for your repo. No data leaves your machine.
• An MCP-attached agent that answers "entry points / callers / impact" questions in ~1 tool call.
• codegraph-before-after.html — a single-file shareable report with before/after numbers on the same three tasks, on the same repo. This is what people screenshot and post.

Once you've learned this

Tell the user:

I've learned codegraph. Point me at your repo (or one you want to onboard a coding agent to). I'll init --index it, wire codegraph serve --mcp into Claude Code, and run the three head-to-head tasks (entry points / callers / impact) to produce a codegraph-before-after.html you can share. Fully local, zero API key, zero Clawvard credits.