ai-codegraph — semantic code intelligence via MCP

What it produces

Nothing written. This skill reads the code graph and returns structured answers: verbatim source grouped by file, call paths (including dynamic dispatch), and blast radius summaries. The agent uses these to answer graph questions without grepping every file.

When to use CodeGraph vs find/grep

Rule of thumb: graph questions → CodeGraph. Text questions → find/grep.

Steps

1. Check availability — is CodeGraph installed?

   which codegraph && codegraph --version

   If missing: npm i -g @colbymchenry/codegraph
2. Check daemon — is the daemon running?

   test -S .codegraph/daemon.sock && echo "running" || echo "not running"

   If not running: codegraph serve --mcp &
3. Check index — is the project indexed?

   codegraph status

   If not indexed: codegraph init
4. Query — use codegraph_explore MCP tool:
   • query: natural language or symbol/file names
   • maxFiles: default 12, increase for broad questions
5. Interpret results — CodeGraph returns:
   • Verbatim source grouped by file (with line numbers)
   • Call paths (calls, imports, extends, implements)
   • Blast radius summary (what depends on the queried symbol)

Per-surface MCP configuration

CodeGraph is an MCP server, not a governance hook. Each surface reads its own config:

Stdio launch shape (all surfaces):

{
  "type": "stdio",
  "command": "codegraph",
  "args": ["serve", "--mcp"]
}

Lifecycle

Lane: light Writes: nothing (read-only tool server) Read by: any agent that needs graph queries Dies: on session end Next: none — the agent decides when to use it based on the question type

Anti-patterns

• Do NOT use for literal text search (grep is faster)
• Do NOT use for file discovery (find/glob is faster)
• Do NOT use CodeGraph AND grep for the same question — pick one
• DO remember: CodeGraph leaves 82% more context resident after multi-turn sessions (vendor data: 67k vs 18k tokens after 3 turns). On small repos (<300 files), the cost may outweigh the benefit.

Source

• Repository: https://github.com/colbymchenry/codegraph
• License: MIT
• Stars: ~71k
• Version: 1.6.0 (measured 2026-09-22)
• Integration evidence: .codegraph/codegraph.db in this workspace

Source: ai-engineering (own), Apache-2.0.