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.
Without GrapeRoot
grep, Bash, ReadThousands of tokens wasted on exploration every turn.
With GrapeRoot
One pass. Zero exploration overhead. Better answers.
Under the Hood
What GrapeRoot does today
When you run graperoot . (or the shortcuts dgc . / 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 compact structured summary with only the relevant context. 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 graperoot
From the moment you type graperoot . (or dgc . / 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 a compact context pack, and injects it directly into your AI's prompt. This happens in milliseconds.
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
To update GrapeRoot and all individual tool launchers at once, run:
graperoot --updateThis updates both the core GrapeRoot engine and all tool-specific shortcuts (dgc, dg, etc.) in one command. Updates are pulled from a Cloudflare R2 CDN for speed and reliability. If the remote version is older than your local version, the update is skipped automatically.
GrapeRoot also checks for updates automatically every time you start a session. You never need to worry about running an outdated version — it stays current on its own.
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.
FAQ
Frequently asked questions
Quick answers to the things people ask most. If your question isn't here, send us a note.
Getting started
Which AI tools does GrapeRoot work with?
How do I install it?
graperoot . on each project. macOS / Linux: curl -sSL …/install.sh | bash. Windows uses irm … | iex. See the install block on the home page for the exact commands.Do I need to run something every session?
graperoot . inside your project folder — it will ask you to pick your AI tool from a menu. Or use the shortcuts directly: dgc . (Claude Code), dg . (Codex). That one command starts the local server and connects your AI.Privacy & local-first
Does my code leave my machine?
.dual-graph/ inside your project. The server runs on localhost — no file names, no source, no project data is ever sent externally.What does GrapeRoot send out, then?
Pro & billing
What do I get in Pro?
How does Pro billing work?
Maintenance & updates
How are updates delivered?
graperoot --update to update everything at once. GrapeRoot also checks for a new version automatically when you start a session and updates in place. You can disable auto-updates with an environment variable if you need a pinned version.What happens when my files change?
How GrapeRoot compares
GrapeRoot vs Repomix
Where GrapeRoot differs: Repomix is static and manual — you regenerate a dump, paste it, and hope it fits. Even with compression, a 500-file repo still produces tens of thousands of tokens. GrapeRoot builds a live dependency graph that automatically selects only the 5–15 files relevant to your current question. It re-indexes incrementally on every file save (sub-second), requires no copy-paste, and pre-injects context before the AI starts — so you never pay for files you don't need. Repomix gives the AI everything; GrapeRoot gives it exactly what matters.
GrapeRoot vs Aider's repo map
Where GrapeRoot differs: GrapeRoot's dual graph stores both structural relationships (imports, call targets, type references) and session-level context (what you asked, what was relevant before). It persists across turns and sessions — not rebuilt per message. When context is needed, GrapeRoot delivers actual function bodies and surrounding code, not just signatures. It also tracks your editing patterns to prioritize recently-touched code. Aider's map tells the AI what exists; GrapeRoot tells it what's relevant and gives it the actual code to work with.
GrapeRoot vs Augment Code
Where GrapeRoot differs: GrapeRoot runs 100% locally — no code ever leaves your machine, no cloud dependency, no vendor lock-in. It's available to individual developers for free, not just enterprise teams. While Augment coordinates multi-agent workflows across SDLC stages, GrapeRoot focuses on one thing and does it exceptionally: delivering the right context to your existing AI tools. In benchmarks, GrapeRoot achieves 50–70% token savings with zero infrastructure setup — just run
graperoot . and it works.GrapeRoot vs Sourcebot
Where GrapeRoot differs: Sourcebot is reactive — your AI must decide to search, formulate a query, make a tool call, wait for results, then decide if it needs more. Each round-trip costs tokens and adds latency. GrapeRoot is proactive — it pre-injects relevant context before the AI even begins thinking about your question. No tool calls, no search queries, no round-trips. The graph already knows which files connect to your question. Sourcebot also requires Docker infrastructure; GrapeRoot is a single CLI command with zero dependencies.
GrapeRoot vs Continue.dev
Where GrapeRoot differs: Embedding-based RAG treats every chunk as independent — it has no understanding of how files import each other, which functions call which, or how types flow through your codebase. Two highly related files with different variable names score low on similarity. GrapeRoot's graph captures structural relationships (imports, exports, call chains, type dependencies), so when one file is relevant, its connected files come along automatically. GrapeRoot also persists session memory across conversations and re-indexes incrementally — no re-embedding your entire codebase after edits.
GrapeRoot vs Cline
Where GrapeRoot differs: Cline's exploration approach means your AI burns tokens every turn just figuring out which files to look at — reading directory listings, opening wrong files, backtracking. In a 200-file project, Cline might read 15–30 files across multiple tool calls before finding what it needs. GrapeRoot eliminates this entirely: the graph pre-computes file relationships, so the AI receives exactly the right files in its first message with zero exploration. Same quality results, 50–70% fewer tokens, and no multi-second tool-call chains.
GrapeRoot vs Graphify
graphify_locate tool that claims 263x fewer tokens than grep+read. Requires explicit graphify_build calls and freshness checks.Where GrapeRoot differs: Graphify is still reactive — your AI must call
graphify_locate or graphify_query as tool calls, paying round-trip latency and output tokens for each query. GrapeRoot pre-injects context before the AI's first response — zero tool calls needed. GrapeRoot also re-indexes automatically on file save (no manual build/freshness commands), maintains persistent session memory across conversations, and tracks editing patterns to weight recently-changed code higher. Graphify gives you tools to ask the graph; GrapeRoot delivers answers from the graph before you even ask.GrapeRoot vs RTK (Rust Token Killer)
cargo test (97.8% reduction), env (99.3%), and cargo clippy (92.5%). It works as a post-processor on 20+ allowlisted commands and integrates via MCP.Where GrapeRoot differs: RTK and GrapeRoot solve completely different problems. RTK compresses output after the AI already decided to run a command — it makes results smaller but doesn't prevent unnecessary work. GrapeRoot works upstream: it decides which files are relevant before the AI starts, so unnecessary commands never get executed in the first place. RTK saves tokens on output; GrapeRoot prevents wasted input tokens entirely. They're complementary — you can run both together for maximum savings — but GrapeRoot alone typically delivers 50–70% total session savings by eliminating the exploration loop that generates noisy output in the first place.
GrapeRoot vs Headroom
headroom wrap claude CLI wrapper. Supports reversible compression (CCR) so originals stay recoverable.Where GrapeRoot differs: These tools solve different problems and work best together. Headroom is downstream — it compresses whatever context you've already decided to send. GrapeRoot is upstream — it decides which files are even worth reading in the first place. If your agent reads 40 files to answer a question, Headroom makes those 40 files cheaper; GrapeRoot ensures it only needs 8 files to begin with. Headroom has no understanding of cross-file relationships, import graphs, or call chains — it compresses each file independently. GrapeRoot's graph knows how files connect, so the right context arrives before exploration starts. Stack them for maximum savings: GrapeRoot selects → Headroom compresses → lowest possible token spend.
Can I use GrapeRoot alongside these tools?
Ready when you are
Install in under a minute.
One global install, then run on any project.
