Paths: File paths are relative to skills repo root.
Code Knowledge Graph
Type: Standalone Utility
Category: 0XX Dev Environment
Indexes codebase into a layered graph (tree-sitter AST → SQLite) and provides dependency analysis, path tracing, references, implementations, and architecture overview via MCP tools.
Inputs
| Input |
Required |
Source |
Description |
project_path |
yes |
args or CWD |
Project root to index |
command |
no |
args |
Specific action: index, search, symbol, paths, refs, arch |
When to Use
- Starting work on an unfamiliar codebase →
index + architecture
- Before refactoring a function/class →
search + get_symbol + trace_paths
- Understanding call flow →
trace_paths
- Finding a symbol quickly →
search
Workflow
Phase 1: Index
Check if graph exists (.codegraph/index.db in project root).
If NOT exists:
Call: index_project({ path: "{project_path}" })
If exists (re-index on demand):
Call: index_project({ path: "{project_path}" })
Idempotent — skips unchanged files automatically.
Phase 2: Query
Route based on user intent:
| User says |
Tool |
Parameters |
| "Show dependencies" / "What uses X?" |
trace_paths |
{ name: "X", file: "...", path_kind: "mixed", direction: "reverse" } |
| "Who calls X?" / "What does X call?" |
trace_paths |
{ name: "X", file: "...", path_kind: "calls", direction: "reverse"|"forward" } |
| "Tell me about X" / "Context of X" |
get_symbol |
{ name: "X", file: "..." } |
| "Project structure" / "Architecture" |
get_architecture |
{ path?: "src/" } |
| "Find symbol X" |
search_symbols |
{ query: "X" } |
| "Watch for changes" |
watch_project |
{ path: "{project_path}" } |
| "Find duplicate code" |
find_clones |
{ type: "all" } |
| "Risky hotspots" |
find_hotspots |
{ minCallers: 2, minComplexity: 5 } |
| "Unused exports" |
find_unused_exports |
{} |
| "Circular dependencies" |
find_cycles |
{} |
| "Module coupling" |
get_module_metrics |
{ minCoupling: 0 } |
| "Implementations / overrides" |
find_implementations |
{ qualified_name: "..." } |
| "Dataflow / propagation" |
find_dataflows |
{ qualified_name: "...", depth: 2 } |
Phase 3: Present Results
- Show MCP tool output directly (markdown tables)
- For code snippets referenced in results, use
hex-line read_file with line ranges
- Suggest follow-up queries based on results:
- After
search_symbols → suggest get_symbol for top result
- After
get_symbol → suggest trace_paths if refactoring
- After
trace_paths → suggest find_references or find_implementations depending on symbol kind
Supported Languages
| Language |
Extensions |
Coverage |
| JavaScript |
.js, .mjs, .cjs, .jsx |
Strongest semantic coverage |
| TypeScript / TSX |
.ts, .tsx |
Strongest semantic coverage |
| Python |
.py |
Definitions, exports, imports; more limited cross-file semantics |
| C# |
.cs |
Definitions, exports, imports, type relations |
| PHP |
.php |
Definitions, exports, imports |
MCP Server Setup
Add to .mcp.json:
{
"mcpServers": {
"hex-graph": {
"command": "node",
"args": ["{skills_repo}/mcp/hex-graph-mcp/server.mjs"]
}
}
}
Definition of Done
Version: 0.1.0
Last Updated: 2026-03-20
1---2name: ln-020-codegraph3description: Builds and queries code knowledge graph for dependency analysis, references, implementations, and architecture overview. Use when starting work on unfamiliar codebase or before refactoring.4license: MIT5---6> **Paths:** File paths are relative to skills repo root.78# Code Knowledge Graph910**Type:** Standalone Utility11**Category:** 0XX Dev Environment1213Indexes codebase into a layered graph (tree-sitter AST → SQLite) and provides dependency analysis, path tracing, references, implementations, and architecture overview via MCP tools.1415## Inputs1617| Input | Required | Source | Description |18|-------|----------|--------|-------------|19| `project_path` | yes | args or CWD | Project root to index |20| `command` | no | args | Specific action: `index`, `search`, `symbol`, `paths`, `refs`, `arch` |2122## When to Use2324- Starting work on an **unfamiliar codebase** → `index` + `architecture`25- Before **refactoring** a function/class → `search` + `get_symbol` + `trace_paths`26- Understanding **call flow** → `trace_paths`27- Finding a **symbol** quickly → `search`2829## Workflow3031### Phase 1: Index3233Check if graph exists (`.codegraph/index.db` in project root).3435**If NOT exists:**36```37Call: index_project({ path: "{project_path}" })38```3940**If exists** (re-index on demand):41```42Call: index_project({ path: "{project_path}" })43```44Idempotent — skips unchanged files automatically.4546### Phase 2: Query4748Route based on user intent:4950| User says | Tool | Parameters |51|---|---|---|52| "Show dependencies" / "What uses X?" | `trace_paths` | `{ name: "X", file: "...", path_kind: "mixed", direction: "reverse" }` |53| "Who calls X?" / "What does X call?" | `trace_paths` | `{ name: "X", file: "...", path_kind: "calls", direction: "reverse"\|"forward" }` |54| "Tell me about X" / "Context of X" | `get_symbol` | `{ name: "X", file: "..." }` |55| "Project structure" / "Architecture" | `get_architecture` | `{ path?: "src/" }` |56| "Find symbol X" | `search_symbols` | `{ query: "X" }` |57| "Watch for changes" | `watch_project` | `{ path: "{project_path}" }` |58| "Find duplicate code" | `find_clones` | `{ type: "all" }` |59| "Risky hotspots" | `find_hotspots` | `{ minCallers: 2, minComplexity: 5 }` |60| "Unused exports" | `find_unused_exports` | `{}` |61| "Circular dependencies" | `find_cycles` | `{}` |62| "Module coupling" | `get_module_metrics` | `{ minCoupling: 0 }` |63| "Implementations / overrides" | `find_implementations` | `{ qualified_name: "..." }` |64| "Dataflow / propagation" | `find_dataflows` | `{ qualified_name: "...", depth: 2 }` |6566### Phase 3: Present Results67681. Show MCP tool output directly (markdown tables)692. For code snippets referenced in results, use `hex-line read_file` with line ranges703. Suggest follow-up queries based on results:71 - After `search_symbols` → suggest `get_symbol` for top result72 - After `get_symbol` → suggest `trace_paths` if refactoring73 - After `trace_paths` → suggest `find_references` or `find_implementations` depending on symbol kind7475## Supported Languages7677| Language | Extensions | Coverage |78|---|---|---|79| JavaScript | .js, .mjs, .cjs, .jsx | Strongest semantic coverage |80| TypeScript / TSX | .ts, .tsx | Strongest semantic coverage |81| Python | .py | Definitions, exports, imports; more limited cross-file semantics |82| C# | .cs | Definitions, exports, imports, type relations |83| PHP | .php | Definitions, exports, imports |8485## MCP Server Setup8687Add to `.mcp.json`:88```json89{90 "mcpServers": {91 "hex-graph": {92 "command": "node",93 "args": ["{skills_repo}/mcp/hex-graph-mcp/server.mjs"]94 }95 }96}97```9899## Definition of Done100101- [ ] Project indexed (index_project returns success)102- [ ] Query results shown to user103- [ ] Follow-up suggestions provided104105---106**Version:** 0.1.0107**Last Updated:** 2026-03-20
onfire7777