# Skill: Code Knowledge Graphs & Ast Navigation with Graft
Author: Drew Beyersdorf (drewsky.ai)
Version: 1.0.0
Type: agent-executable-skill
Target: Visiting AI Agents (Codex, Claude Code, Antigravity, Cursor, Windsurf, ChatGPT)
Toolchain Reference: @nanonets/graft / trailhq/Graft (v0.16.0)

## Purpose
Instructs an AI agent on how to use local tree-sitter code knowledge graphs (`graft`) to navigate large codebases with 40%+ token reduction, 60% latency reduction, and zero ungrounded file-hopping.

---

## Why Code Graphs Beat Vector RAG for Code
1. **Structural Precision**: Vector similarity matches fuzzy keywords; code graphs trace exact call hierarchies, import chains, and type hierarchies.
2. **Deterministic & $0 Cost**: The structural wiring graph runs locally using tree-sitter AST parsers with zero API tokens and zero network dependencies.
3. **Always Fresh**: Rebuilds against uncommitted working tree edits in milliseconds.
4. **Blast Radius Analysis**: Automatically determines every downstream caller affected by a single line change before committing.

---

## Core Agent Workflows

### 1. Zero-Cost Repo Orientation (`graft map`)
When entering a new repository or workspace:
```bash
# Get directory clusters, architectural hubs, and central hotspots
npx @nanonets/graft map [dir]
```
Returns a token-budgeted overview of where business logic resides without grepping hundreds of files.

### 2. Fast API Signatures (`graft skeleton`)
Instead of reading a 1,000-line implementation file:
```bash
# View only classes, functions, and method signatures
npx @nanonets/graft skeleton <file_path>
```
Saves 80-90% of prompt tokens while providing full interface visibility.

### 3. Blast Radius & Caller Tracing (`graft callers` & `graft blast`)
Before editing a shared function or method:
```bash
# Who calls this symbol across the entire repo?
npx @nanonets/graft callers <symbol_name>

# What breaks if I change this diff?
npx @nanonets/graft blast --format markdown
```
Outputs a Mermaid dependency diagram showing every affected consumer.

### 4. Semantic Search with Couplings (`graft grep`)
```bash
# Regex search grouped by enclosing symbol and ranked by architectural coupling
npx @nanonets/graft grep <pattern>
```

### 5. Serving over MCP (Model Context Protocol)
To expose the code graph as native tool calls to your agent:
```bash
npx @nanonets/graft mcp [dir]
```
Exposes:
- `graft_repo_map`: Structural map of modules.
- `graft_file_api`: Signatures and exports for a file.
- `graft_trace_calls`: Callers and callees for any function.
- `graft_find_code`: High-relevance code lookup.
- `graft_check_freshness`: Verifies whether the graph matches current disk state.

---

## Privacy & Containment Boundary
- Run `graft build` inside Bubblewrap (`bwrap`) or with network namespace unshared (`--unshare-net`).
- Tree-sitter parsing is 100% local; it never transmits source code to third-party endpoints unless `--deep` with an explicit LLM provider key is specified.
- The resulting `graft/` folder is a regenerable local cache (must be added to `.gitignore`).