The Problem
Why your AI wastes tokens exploring your codebase
Every time you ask Claude Code or Codex a question about your project, it has to figure out which files are relevant. It does this by making tool calls — reading files one by one, grepping for patterns, exploring directories. On a mid-size project, a single question can trigger 10-20 tool calls before the AI even starts answering.
Each of those tool calls adds overhead. The tool definitions, the system instructions, the back-and-forth — it all compounds. By the time Claude has enough context to answer, it has already burned through thousands of tokens just on exploration.
And it gets worse across turns. Claude does not remember what it explored last time. Next question? Same exploration tax all over again.
The Evolution
How we got here
GrapeRoot started as an MCP server that gave Claude access to a code graph through tool calls. Claude would call graph_continue to find relevant files, then graph_read to read them. It worked — Claude found the right files faster than exploring on its own.
But we noticed a problem. Every MCP tool call added protocol overhead — tool definitions, routing instructions, response formatting. Over a multi-turn session, this overhead added up. Claude was spending fewer tokens on exploration but more tokens on the MCP protocol itself.
The insight
The graph already knows which files matter before Claude asks. So instead of giving Claude tools to query the graph, why not just give it the answer upfront?
That led to Pre-Injection — the current architecture. GrapeRoot retrieves the relevant context locally (in milliseconds), packs it into a compact structured summary, and injects it directly into Claude's prompt. Claude gets everything it needs on the first turn. No tool calls, no multi-turn exploration, no protocol overhead.
Before — MCP Tool Calls
graph_continuegraph_read x3Multiple round trips. Protocol overhead on each.
Now — Pre-Injection
One pass. Zero protocol overhead. Better answers.
Under the Hood
What GrapeRoot does today
When you run dgc . or dg ., GrapeRoot builds a dual graph of your project and uses it to deliver precise context. Here is what each layer does.
Code Map
Your project's DNA
A complete graph of your codebase — every file, function, class, and how they connect through imports and calls. Built in seconds, updated incrementally when files change.
- →Files, functions, classes with line ranges
- →Import and dependency edges between files
- →Keyword scoring for semantic file ranking
Context Packer
The intelligence layer
Takes the graph results and compresses them into a structured summary that fits in ~4,000 tokens. Claude gets function signatures, parameters, return types, and call relationships — not raw file dumps.
- →Full function signatures with params and returns
- →Inline code from the most relevant functions
- →Key dependency edges and call targets
Session Memory
Gets smarter every turn
A live action graph tracks what has been read, edited, and decided during your session. On follow-up questions, GrapeRoot routes directly to previously-touched files with confidence=high — no retrieval needed. Decisions and context carry over between sessions via hooks.
Turn 1
Context packed from graph. Claude learns your project.
Turn 2+
Memory kicks in. Files from previous turns served instantly.
Next Session
Decisions and context injected at startup. No cold start.
Structured summaries over raw files
Instead of dumping entire files into the prompt, GrapeRoot extracts structured summaries: function names, parameter types, return types, decorators, and internal call graphs. Claude gets the same understanding in a fraction of the tokens.
Code-first packing
When Claude needs to see actual code (not just summaries), GrapeRoot inlines the most relevant function bodies directly. The packer prioritizes code over metadata — up to 45% of the token budget goes to inline code from the top functions per file.
Session Flow
What happens when you run dgc / dg
From the moment you type dgc . or dg . to your AI answering your first question — here is every step.
GrapeRoot walks your project directory, extracts files, functions, classes, import edges, and builds the dual graph. This takes seconds, even on large projects. Unchanged files are cached.
A lightweight local server starts on a free port (8080-8099). It serves the graph tools and handles context packing. Claude Code or Codex connects automatically.
GrapeRoot writes hooks into Claude's local settings. These re-inject context when Claude compacts its memory mid-conversation, and log token usage at session end.
GrapeRoot retrieves the relevant files from the graph, packs structured summaries and inline code into ~4,000 tokens, and injects it into Claude's prompt. This happens in ~150ms.
Claude has function signatures, call graphs, and relevant code from the start. No exploration needed. It goes straight to answering your question.
Built-in guardrails
GrapeRoot enforces per-turn read budgets, deduplicates repeated reads, and rate-limits fallback grep calls. Your AI stays efficient without you having to micromanage it.
Cross-Platform
Works everywhere, sets itself up
GrapeRoot runs on macOS, Linux, and Windows. The launcher automatically handles Python discovery, virtual environment creation, and dependency installation — no manual setup required.
macOS
Finds Homebrew Python, Xcode stubs, versioned binaries. Five fallback methods for venv creation.
Linux
Auto-installs missing packages (python3-venv, curl) via apt, yum, dnf, or pacman. Pre-flight checks for Node.js.
Windows
Discovers Python via PATH, py launcher, common install paths, and Conda. Skips the Windows Store stub automatically.
If something goes wrong, GrapeRoot shows clear error messages with specific fix commands for your platform — not cryptic stack traces.
Token Tracking
See what every session costs
GrapeRoot includes a built-in token tracker that runs alongside your AI session. It gives you a live dashboard where you can see exactly how many tokens you are using and what it costs.
You can also ask Claude directly during your session — “how many tokens have I used?” or “what's my cost so far?” — and get an instant answer.
Updates
Always up to date
Every time you run dgc . or dg ., GrapeRoot checks for updates and installs them automatically. You never need to manually update or reinstall — just keep using it and you will always be on the latest version.
Updates are pulled from a Cloudflare R2 CDN for speed and reliability. The launcher re-executes itself after updating, so you always start with the latest code. If the remote version is older than your local version, the update is skipped automatically.
Privacy
All data stays on your machine
Everything GrapeRoot does happens locally on your computer. Your source code is never sent anywhere. The graph, the session memory, the context packs — all stored in <project>/.dual-graph/ on your machine.
Your code never leaves your machine
The server runs on localhost. No file names, no code, and no project data is ever sent externally.
No account required
No sign-up, no API keys, no cloud dashboard. Install and go.
The only outbound calls are an anonymous version check (a single GET request for a version string) and an optional one-time feedback prompt after the first day of use.