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 →
```
find_symbols
```
+
```
inspect_symbol
```
+
```
trace_paths
```
Understanding call flow →
```
trace_paths
```
Finding a symbol quickly →
```
search
```

MCP Availability

Tool policy: follow host AGENTS.md MCP preferences; load

references/mcp_tool_preferences.md

and

references/mcp_integration_patterns.md

only when host policy is absent or MCP behavior is unclear.

Use

hex-graph

first when the task depends on symbol identity, references, implementations, architecture, dataflow, or edit impact. Use

hex-line

first for targeted local code reads when available. If MCP is unavailable, unsupported, or not indexed, continue with built-in

Glob/Grep/Read/Bash

, answer with manual evidence, and explicitly note the degraded confidence instead of blocking the skill.

Workflow

Phase 1: Index

Check if graph exists (

.hex-skills/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.

If
hex-graph
is unavailable: build a manual project map with

Glob

and targeted

Grep/Read

, then continue to the closest matching query workflow without indexing.

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", path: "{project_path}" }`
"Who calls X?" / "What does X call?"	`trace_paths`	`{ name: "X", file: "...", path_kind: "calls", direction: "reverse"\|"forward", path: "{project_path}" }`
"Tell me about X" / "Context of X"	`inspect_symbol`	`{ name: "X", file: "...", path: "{project_path}" }`
"Project structure" / "Architecture"	`analyze_architecture`	`{ path: "{project_path}", scope?: "src/" }`
"Find symbol X"	`find_symbols`	`{ path: "{project_path}", query: "X" }`
"Find `app.get(...)` / `router.use(...)` / `server.registerTool(...)` pattern"	`grep_search`	`{ path: "{project_path}", pattern: "app\.get\(
"Find duplicate code / hotspots / unused exports"	`audit_workspace`	`{ path: "{project_path}", scope?: "src/", verbosity: "minimal", limit: 5, clone_member_limit: 3 }`
"Circular dependencies / module coupling"	`analyze_architecture`	`{ path: "{project_path}", verbosity: "full" }`
"Implementations / overrides"	`find_implementations`	`{ name: "X", file: "...", path: "{project_path}" }`
"Dataflow / propagation"	`trace_dataflow`	`{ source: { symbol: { name: "X", file: "..." }, anchor: { kind: "param", name: "input" } }, sink?: { symbol: { name: "X", file: "..." }, anchor: { kind: "return" } }, path: "{project_path}" }`
"Review a diff / worktree"	`analyze_changes`	`{ path: "{project_path}", base_ref: "origin/main" }`
"Check what editing this range affects"	`analyze_edit_region`	`{ path: "{project_path}", file: "src/file.ts", line_start: 10, line_end: 40 }`

Canonical selector rule: Semantic tools accept exactly one selector:

```
symbol_id
```
```
workspace_qualified_name
```
```
qualified_name
```
```
name
```
+
```
file
```

Preferred flow: use

find_symbols

only after narrowing

path

as much as practical, then feed the returned

workspace_qualified_name

into

inspect_symbol

trace_paths

find_references

, or

find_implementations

for exact follow-up queries.

Query boundary rule:

find_symbols

is name-based discovery only. For code fragments like

export function

or unresolved member-call patterns like

app.get(...)

, use

grep_search

instead of treating them as symbols.

Ambiguity rule: if

find_symbols

returns

partial ... truncated=1

or shows more total results than returned rows, refine with

path

, then

name + file

workspace_qualified_name

instead of widening the graph query.

Path rule:

path

may be the indexed project root or any file/subdirectory inside that indexed project.

Dataflow anchors:

trace_dataflow

requires

source.anchor

and optional

sink.anchor

. Use:

```
param
```
for function parameters
```
local
```
for local variables
```
return
```
for function returns
```
property
```
with
```
access_path
```
for bounded property flow

Precision controls:

inspect_symbol

trace_paths

, and

find_references

support

min_confidence

(

low

inferred

exact

precise

) when the caller wants to suppress weaker parser-only facts.

Phase 3: Present Results

Show MCP tool output directly when available; otherwise present manual findings and mark them as fallback reasoning
For code snippets referenced in results, use
```
hex-line read_file
```
with line ranges when available; otherwise use built-in
```
Read
```
Suggest follow-up queries based on results:

After

find_symbols

with a clean top match → suggest

inspect_symbol

with

workspace_qualified_name

After
```
find_symbols
```
with
```
partial ... truncated=1
```
→ suggest narrowing
```
path
```
or switching to
```
name + file
```
before any deeper graph tool
After
```
inspect_symbol
```
→ suggest
```
trace_paths
```
if refactoring

After

trace_paths

→ suggest

find_references

find_implementations

depending on symbol kind

After empty
```
trace_paths
```
from a broad or module-level selector → suggest
```
inspect_symbol
```
or
```
analyze_architecture
```
instead of assuming there are no dependencies

Supported Languages

Language	Extensions	Coverage
JavaScript	.js, .mjs, .cjs, .jsx	Strongest semantic coverage
TypeScript / TSX	.ts, .tsx	Strongest semantic coverage
Python	.py	Workspace-aware definitions, calls, imports, unused exports; optional precise overlay when provider is installed
C#	.cs	Workspace-aware definitions, calls, project/namespace ownership, type relations; optional precise overlay when provider is installed
PHP	.php	Workspace-aware definitions, calls, PSR-4 namespace imports, unused exports; optional precise overlay when provider is installed

MCP Server Setup

Add to

.mcp.json

json

{
  "mcpServers": {
    "hex-graph": {
      "command": "node",
      "args": ["{skills_repo}/mcp/hex-graph-mcp/server.mjs"]
    }
  }
}

Definition of Done

Project indexed or manual fallback map built
Query results shown to user
Follow-up suggestions provided
Fallback path stated when MCP was unavailable

Version: 0.1.0 Last Updated: 2026-03-20

ln-021-codegraph

NPX Install

Tags

SKILL.md Content