ai-codegraph
Uses local CodeGraph MCP for symbol relationships, call chains, and blast radius. Trigger: "how does X work", "what calls Y", "what depends on", or "what breaks if changed". Not for text search (rg) or file discovery (glob).
Install
npx skills add https://github.com/arcasilesgroup/ai-engineering/tree/main/skills/ai-codegraph
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install arcasilesgroup-ai-engineering@llmmart
git clone https://github.com/arcasilesgroup/ai-engineering.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole arcasilesgroup/ai-engineering collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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
| Question | Tool | Why |
|---|---|---|
| "How does X work?" | codegraph_explore |
Follows call chains across files |
| "What calls function Y?" | codegraph_explore |
Graph traversal, follows polymorphism |
| "If I change this interface, what breaks?" | codegraph_explore |
Blast radius via edge traversal |
| "What does this module depend on?" | codegraph_explore |
Import edges in the graph |
| "Find all TODOs" | grep |
Literal text search, faster |
| "Where is X defined?" | find |
Simple path lookup |
| "Find all files importing X" | grep |
Literal text match |
| "Show me the test for this function" | find + grep |
Convention-based lookup |
Rule of thumb: graph questions → CodeGraph. Text questions → find/grep.
Steps
Check availability — is CodeGraph installed?
which codegraph && codegraph --versionIf missing:
npm i -g @colbymchenry/codegraphCheck daemon — is the daemon running?
test -S .codegraph/daemon.sock && echo "running" || echo "not running"If not running:
codegraph serve --mcp &Check index — is the project indexed?
codegraph statusIf not indexed:
codegraph initQuery — use
codegraph_exploreMCP tool:query: natural language or symbol/file namesmaxFiles: default 12, increase for broad questions
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:
| Surface | Config file | Key |
|---|---|---|
| Claude Code | ~/.claude.json (global) or .mcp.json (project) |
mcpServers.codegraph |
| Cursor | ~/.cursor/mcp.json (global) or .cursor/mcp.json (project) |
mcpServers.codegraph |
| Copilot VS Code | .vscode/mcp.json (local) or user mcp.json |
servers.codegraph |
| Copilot CLI | ~/.copilot/mcp-config.json |
mcpServers.codegraph |
| opencode | ~/.config/opencode/opencode.jsonc |
mcp.servers.codegraph |
| OMP | Import from ~/.claude.json or add manually |
— |
| Pi | pi-codegraph-extension or @isac322/pi-codegraph |
— |
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 (
grepis faster) - Do NOT use for file discovery (
find/globis 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.dbin this workspace
Source: ai-engineering (own), Apache-2.0.
Files (ai-engineering)
-
SKILL.md 3.9 KB
--- name: ai-codegraph description: >- Uses local CodeGraph MCP for symbol relationships, call chains, and blast radius. Trigger: "how does X work", "what calls Y", "what depends on", or "what breaks if changed". Not for text search (rg) or file discovery (glob). license: Apache-2.0 --- # 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 | Question | Tool | Why | |----------|------|-----| | "How does X work?" | `codegraph_explore` | Follows call chains across files | | "What calls function Y?" | `codegraph_explore` | Graph traversal, follows polymorphism | | "If I change this interface, what breaks?" | `codegraph_explore` | Blast radius via edge traversal | | "What does this module depend on?" | `codegraph_explore` | Import edges in the graph | | "Find all TODOs" | `grep` | Literal text search, faster | | "Where is X defined?" | `find` | Simple path lookup | | "Find all files importing X" | `grep` | Literal text match | | "Show me the test for this function" | `find` + `grep` | Convention-based lookup | **Rule of thumb:** graph questions → CodeGraph. Text questions → find/grep. ## Steps 1. **Check availability** — is CodeGraph installed? ```bash which codegraph && codegraph --version ``` If missing: `npm i -g @colbymchenry/codegraph` 2. **Check daemon** — is the daemon running? ```bash test -S .codegraph/daemon.sock && echo "running" || echo "not running" ``` If not running: `codegraph serve --mcp &` 3. **Check index** — is the project indexed? ```bash 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: | Surface | Config file | Key | |---------|------------|-----| | Claude Code | `~/.claude.json` (global) or `.mcp.json` (project) | `mcpServers.codegraph` | | Cursor | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) | `mcpServers.codegraph` | | Copilot VS Code | `.vscode/mcp.json` (local) or user mcp.json | `servers.codegraph` | | Copilot CLI | `~/.copilot/mcp-config.json` | `mcpServers.codegraph` | | opencode | `~/.config/opencode/opencode.jsonc` | `mcp.servers.codegraph` | | OMP | Import from `~/.claude.json` or add manually | — | | Pi | `pi-codegraph-extension` or `@isac322/pi-codegraph` | — | **Stdio launch shape** (all surfaces): ```json { "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.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.