← All posts

· 6 min read

Your AI Assistant Doesn't Understand Your Codebase. Here's the Fix That Lives Inside Your Repo.

A look at Draft's knowledge graph engine — deterministic codebase understanding for AI assistants, with no MCP server, no SaaS, no API key, no leaked code.

The Bottom Line

Most "AI for code" tools improve context by sending more of your code to a third party — vector DBs, MCP servers, indexing services, hosted retrieval pipelines. Draft's graph engine takes the opposite path: a local, deterministic, version-controlled knowledge graph of your repo, built by a Node.js binary that ships with the plugin and writes plain JSONL into draft/graph/.

No external service. No embeddings. No network call. No new account. Your AI assistant gets sharper context because the structural truth of your codebase — modules, dependencies, hotspots, call edges, proto APIs — is sitting next to the code it's reasoning about, in files you can git diff.

Why "Better Context" Usually Means "More Cloud"

Walk through the standard playbook for giving an LLM context on a large codebase:

  1. Stand up a vector database.
  2. Pick an embedding model (and pay per token to index your repo).
  3. Run a chunker, hope the chunk boundaries respect function scopes.
  4. Wire an MCP server or hosted retrieval API.
  5. Re-index on every meaningful change.
  6. Pray the semantic search returns the right five files for the prompt.

Every step adds latency, cost, a vendor, a secret to manage, and a question about where your proprietary code now lives. And the output is still probabilistic — "files that look similar to your query" is not the same as "files that actually call this function."

For regulated environments (finance, healthcare, defense, on-prem GPU clusters), most of this isn't even allowed.

What Draft Does Instead

Draft ships a graph binary written in Node.js + tree-sitter WASM. You run it once during /draft:init, and it writes a structured, deterministic snapshot of your repo into draft/graph/:

draft/graph/
├── schema.yaml              # metadata, stats, module list
├── module-graph.jsonl       # weighted inter-module dependency edges
├── hotspots.jsonl           # files ranked by complexity (lines + fanIn × 50)
├── proto-index.jsonl        # all gRPC services, RPCs, messages
├── go-index.jsonl           # Go funcs, types, imports, call edges
├── python-index.jsonl       # Python funcs, classes, imports, call edges
├── ts-index.jsonl           # TS/JS funcs, classes, call edges
├── c-index.jsonl            # C/C++ funcs, types, call edges
├── call-index.jsonl         # cross-language call edges
└── modules/<name>.jsonl     # per-module file graph (loaded on demand)

Every record is JSONL. Every file is plain text. The whole thing is meant to be checked into git.

Five Properties That Change How AI Reasons About Your Code

1. Deterministic, Not Probabilistic

A vector search asks "which chunks look semantically related?" The graph answers "which functions actually call buildGoIndex?" — by name, with file paths and line numbers.

graph --query --symbol buildGoIndex --mode callers

Output:

{
  "target": "buildGoIndex",
  "callers": [{"func": "...", "file": "...", "module": "...", "line": 142}],
  "by_module": {...}
}

The AI no longer guesses. It reads a fact.

2. Zero External Services

Standard "AI context" stackDraft graph
Vector DB (Pinecone, Weaviate, pgvector)None
Embedding API (OpenAI, Voyage, Cohere)None
MCP server / hosted retrievalNone
Re-indexing pipeline--incremental flag, content-hashed
Per-token indexing cost$0
Code leaves your machineNever

The graph engine is one Node.js process reading your source files.

3. Version-Controlled Context

draft/graph/*.jsonl are text files. Commit them. Diff them. Review them in PRs.

When a refactor lands, the graph diff shows what structural relationships changed — new edges added, hotspot ranks shifted, cycles introduced. Your code review now includes the architecture review, automatically. No dashboard required.

4. Blast-Radius Queries Before You Edit

Before changing a file, ask the graph what depends on it:

graph --query --file auth/auth.h --mode impact

You get back:

{
  "impact": {
    "files": 47,
    "modules": 6,
    "by_category": {"code": 31, "test": 12, "doc": 3, "config": 1},
    "files_by_depth": {...}
  }
}

The AI assistant — and you — now know exactly how many tests to update, which docs go stale, which configs ship the change. No "I think this might be safe."

5. Hotspots and Cycles, Cheaply

graph --query --mode hotspots          # files ranked by lines + fanIn × 50
graph --query --mode cycles            # circular module dependencies
graph --query --mode mermaid           # ready-to-paste architecture diagrams

This is the kind of thing teams used to commission a consultant to produce as a PDF. It now runs in seconds, on every commit, for free, locally.

How the AI Actually Uses This

Draft's skills (/draft:implement, /draft:review, /draft:bughunt, /draft:debug, /draft:decompose) are wired to call the graph during context loading. Concretely:

  • /draft:implement queries impact + hotspots before writing a plan, so the proposed change lists every test and downstream file by name.
  • /draft:review pulls call edges and module dependencies to flag changes that touch hub modules or break module boundaries.
  • /draft:bughunt walks call edges to widen the search radius around a suspect function, deterministically, without spraying tokens at unrelated files.
  • /draft:debug uses callers + impact to scope the investigation rather than asking the LLM to grep.

When draft/graph/ is absent, every skill degrades silently — the graph enriches reasoning, it never gates it.

What This Means for the Three People Reading This

If you're an engineer: stop pasting whole repos into a chat window. A 30-second graph --repo . produces a context layer your AI assistant can actually navigate, and it costs nothing per query.

If you're an engineering leader: the graph is your audit trail for AI-assisted changes. Every PR can show which structural relationships shifted. No vendor lock-in, no data egress, no compliance review for a new SaaS.

If you work in a regulated or air-gapped environment: this is the entire point. The graph runs on a laptop, on a build agent, on a DGX node behind a firewall. Code never leaves the box. Your AI workflow finally has a context strategy that legal will sign off on.

The Larger Argument

The industry default for "AI + code" is to bolt more cloud onto your repo. Draft's bet is the opposite: the artifact that makes AI useful on a codebase is a deterministic structural index that lives next to the code, in the same git history, refreshable in seconds, readable by humans and machines alike.

Embeddings have a place. Vector search has a place. Hosted retrieval has a place. But for the question every AI assistant actually asks — "what does this code touch, and what touches it?" — the right answer is a graph, on disk, in your repo, under your control.

Try It

# Install Draft (Claude Code plugin)
# https://getdraft.dev

cd your-repo
/draft:init                                 # builds the graph as part of init

# Or run the engine directly:
graph --repo . --out draft/graph/
graph --repo . --query --mode hotspots
graph --repo . --query --file path/to/file --mode impact

Then commit draft/graph/. Your repo now carries its own structural memory — and your AI assistant just got a lot less guessy.