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
7> **Paths:** File paths are relative to skills repo root.
8
9# Code Knowledge Graph
10
11**Type:** Standalone Utility
12**Category:** 0XX Dev Environment
13
14Indexes codebase into a layered graph (tree-sitter AST → SQLite) and provides dependency analysis, path tracing, references, implementations, and architecture overview via MCP tools.
15
16## Inputs
17
18| Input | Required | Source | Description |
19|-------|----------|--------|-------------|
20| `project_path` | yes | args or CWD | Project root to index |
21| `command` | no | args | Specific action: `index`, `search`, `symbol`, `paths`, `refs`, `arch` |
22
23## When to Use
24
25- Starting work on an **unfamiliar codebase** → `index` + `architecture`
26- Before **refactoring** a function/class → `search` + `get_symbol` + `trace_paths`
27- Understanding **call flow** → `trace_paths`
28- Finding a **symbol** quickly → `search`
29
30## Workflow
31
32### Phase 1: Index
33
34Check if graph exists (`.codegraph/index.db` in project root).
35
36**If NOT exists:**
37```
38Call: index_project({ path: "{project_path}" })
39```
40
41**If exists** (re-index on demand):
42```
43Call: index_project({ path: "{project_path}" })
44```
45Idempotent — skips unchanged files automatically.
46
47### Phase 2: Query
48
49Route based on user intent:
50
51| User says | Tool | Parameters |
52|---|---|---|
53| "Show dependencies" / "What uses X?" | `trace_paths` | `{ name: "X", file: "...", path_kind: "mixed", direction: "reverse" }` |
54| "Who calls X?" / "What does X call?" | `trace_paths` | `{ name: "X", file: "...", path_kind: "calls", direction: "reverse"\|"forward" }` |
55| "Tell me about X" / "Context of X" | `get_symbol` | `{ name: "X", file: "..." }` |
56| "Project structure" / "Architecture" | `get_architecture` | `{ path?: "src/" }` |
57| "Find symbol X" | `search_symbols` | `{ query: "X" }` |
58| "Watch for changes" | `watch_project` | `{ path: "{project_path}" }` |
59| "Find duplicate code" | `find_clones` | `{ type: "all" }` |
60| "Risky hotspots" | `find_hotspots` | `{ minCallers: 2, minComplexity: 5 }` |
61| "Unused exports" | `find_unused_exports` | `{}` |
62| "Circular dependencies" | `find_cycles` | `{}` |
63| "Module coupling" | `get_module_metrics` | `{ minCoupling: 0 }` |
64| "Implementations / overrides" | `find_implementations` | `{ qualified_name: "..." }` |
65| "Dataflow / propagation" | `find_dataflows` | `{ qualified_name: "...", depth: 2 }` |
66
67### Phase 3: Present Results
68
691. Show MCP tool output directly (markdown tables)
702. For code snippets referenced in results, use `hex-line read_file` with line ranges
713. Suggest follow-up queries based on results:
72 - After `search_symbols` → suggest `get_symbol` for top result
73 - After `get_symbol` → suggest `trace_paths` if refactoring
74 - After `trace_paths` → suggest `find_references` or `find_implementations` depending on symbol kind
75
76## Supported Languages
77
78| Language | Extensions | Coverage |
79|---|---|---|
80| JavaScript | .js, .mjs, .cjs, .jsx | Strongest semantic coverage |
81| TypeScript / TSX | .ts, .tsx | Strongest semantic coverage |
82| Python | .py | Definitions, exports, imports; more limited cross-file semantics |
83| C# | .cs | Definitions, exports, imports, type relations |
84| PHP | .php | Definitions, exports, imports |
85
86## MCP Server Setup
87
88Add to `.mcp.json`:
89```json
90{
91 "mcpServers": {
92 "hex-graph": {
93 "command": "node",
94 "args": ["{skills_repo}/mcp/hex-graph-mcp/server.mjs"]
95 }
96 }
97}
98```
99
100## Definition of Done
101
102- [ ] Project indexed (index_project returns success)
103- [ ] Query results shown to user
104- [ ] Follow-up suggestions provided
105
106---
107**Version:** 0.1.0
108**Last Updated:** 2026-03-20
majiayu000