Ln 020 codegraph

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

1. Show MCP tool output directly (markdown tables)
2. For code snippets referenced in results, use hex-line read_file with line ranges
3. 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

• Project indexed (index_project returns success)
• Query results shown to user
• Follow-up suggestions provided

---

Version: 0.1.0 Last Updated: 2026-03-20