Setup guide

Everything after npm i -g and codegraph init: keep the server alive, confirm MCP, add editor rules, then optional advanced layers.

Post-installation

codegraph init already configures your LLM, indexes the repo (if you chose to), prints MCP JSON for Cursor / Claude Code / Windsurf, and tells you to run codegraph serve. The steps below are what most teams do next.
Run the MCP server
codegraph serve

Leave this running in a dedicated terminal. Health check:

curl -sf http://127.0.0.1:3748/healthz
Confirm MCP in your editor

Your client should list codegraph as connected with 26 tools. If not, use the accordion below for Cursor, Claude Code, or Windsurf JSON.

  • Cursor — Settings → MCP
  • Claude Code — type /mcp
  • Windsurf — Cascade, then /refresh-tools
Add editor rules (recommended)

Rules nudge the assistant to call graph tools instead of reading whole trees. See Editor rules below — copy the Cursor .mdc or Claude CLAUDE.md template into your repo and commit it.

Generate AGENTS.md (optional)

After indexing, synthesize a team-wide context file from the graph:

codegraph generate agents-md .

Writes AGENTS.md at the repo root (features, entry points, routes). Works well in Cursor, Claude Code, and other agents that read AGENTS.md.

Smoke-test a tool

Ask your editor: "What calls formatPrice and what's the blast radius of renaming it?" — you should see MCP tool calls like find_callers or blast_radius, not a full-repo file read.

Editor rules

MCP alone does not force the model to use it. Project rules make structural questions go through the graph first — that's where the token savings come from.

Cursor — .cursor/rules/codegraph.mdc

Create this file in your repo (commit it so the whole team gets it):

---
description: Prefer Codegraph MCP for structural codebase questions
globs: *
alwaysApply: true
---

When the user asks about callers, blast radius, features, ownership, git history,
stale docs, dead code, or team memory — use the **codegraph** MCP tools first.
Do not grep entire directories or read full files when a graph tool can answer.

Prefer: find_callers, blast_radius, search_semantic, describe_feature, who_owns,
recent_changes, co_change_partners, recall, search_memory, explain, find_dead_code.

If tools fail with connection errors, remind the user to run `codegraph serve`.
If auth fails, check the bearer token in ~/.codegraph/config.json.

Cursor also reads AGENTS.md at the repo root — generate one with codegraph generate agents-md .

Claude Code — CLAUDE.md

Add at the repository root (Claude Code loads this automatically):

# Codegraph

This repo is indexed locally. For structural questions, use the **codegraph**
MCP server before reading large parts of the tree.

- Callers / blast radius → MCP tools, not full-file dumps
- Features & boundaries → describe_feature, list_features
- Ownership & recent edits → who_owns, recent_changes, co_change_partners
- Past decisions → recall, search_memory, recent_decisions

Keep `codegraph serve` running on http://127.0.0.1:3748/mcp.
Run `codegraph doctor` on 401/403 or connection errors.

MCP wiring: claude mcp add --transport sse codegraph http://127.0.0.1:3748/mcp --header "Authorization: Bearer YOUR_TOKEN" — or use the .mcp.json snippet from codegraph init.

AGENTS.md — all editors

codegraph generate agents-md .

Produces an LLM-written AGENTS.md from your indexed graph. Pair it with the Cursor rule or CLAUDE.md above for best results.

Advanced setup

MCP endpoint & auth

Server URL: http://127.0.0.1:3748/mcp. Bearer token in ~/.codegraph/config.json (mcpToken or server.bearerToken).

jq -r '.mcpToken // .server.bearerToken' ~/.codegraph/config.json

Health check: curl -sf http://127.0.0.1:3748/healthz. Override port with codegraph serve --port N or CODEGRAPH_PORT.

Cursor

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "codegraph": {
      "url": "http://127.0.0.1:3748/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Settings → MCP — codegraph should show connected with 26 tools. Run codegraph serve first.

Claude Code

CLI shortcut:

claude mcp add --transport sse codegraph \
  http://127.0.0.1:3748/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Or add .mcp.json at the project root with type: "sse" and the same URL + headers. Type /mcp to verify 26 tools.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "codegraph": {
      "serverUrl": "http://127.0.0.1:3748/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Restart Windsurf or run /refresh-tools in Cascade.

Manual setup & troubleshooting

Skip the wizard when you need fine control:

codegraph config llm set byo-openai
export OPENAI_API_KEY=sk-...
codegraph config llm test
codegraph index ~/my-project
codegraph serve
  • codegraph doctor — Node, config, API keys, Kuzu, LLM round-trip
  • 401/403 — wrong or missing bearer token; re-read config and update client
  • ECONNREFUSED — server not running; start codegraph serve
  • Re-index after switching LLM provider (embedding namespace changes)

Full client setup guide on GitHub.

Meaning, history & memory

The graph isn't just code structure — these commands layer in the rest of your codebase context.

codegraph generate agents-md .            # auto-write AGENTS.md from the graph
codegraph features build                # cluster + name features (Louvain + LLM)
codegraph features list
codegraph history ingest --since 90     # commits, authors, co-change pairs
codegraph coverage ingest lcov.info     # lcov / cobertura / jest summary
codegraph errors ingest --sentry        # production error frequency
codegraph remember formatPrice "always round before display"
codegraph memory ingest                 # distill chats + decisions
codegraph memory promote                # raw → team-shareable .codegraph/memory/

Each layer adds new MCP tools: explain, find_stale_docs, describe_feature, who_owns, recent_changes, co_change_partners, coverage, health, recall, recent_decisions, search_memory.

Local brain (SLM orchestrator)

A small local model plans tool calls, prunes context, and validates frontier-model output before it reaches your editor. Routes ~80% of questions without ever calling Claude or GPT-4.

codegraph brain models          # detect Ollama + recommend a model for your hardware
codegraph brain start           # boot the local orchestrator
codegraph brain stats           # tokens + cost saved vs an all-frontier baseline

Adds deterministic refactor tools to MCP — no LLM in the loop:

  • rename_symbol — graph-aware rename across every caller
  • extract_module — move symbols and update imports
  • find_dead_code — zero incoming edges, not exported, not in tests
  • codegraph_plan / codegraph_execute — structured plans the editor can review before running

Recipes by RAM: 8 GB → phi-3-mini, 16 GB → qwen2.5-coder:7b, 32 GB+ → qwen2.5-coder:14b.

Uninstall

Remove the CLI, local graph data, and client config:

npm uninstall -g @leanlabsinnov/codegraph
rm -rf ~/.codegraph

Also delete the codegraph entry from .cursor/mcp.json, .mcp.json, or ~/.codeium/windsurf/mcp_config.json if you added one. Stop any running codegraph serve process first.