GrapeRoot

---

What is GrapeRoot?

GrapeRoot is an open-source launcher that sits between you and your AI coding assistant. It builds a semantic graph of your codebase — files, symbols, imports, call chains — and pre-loads exactly the right code into every prompt before your AI sees it.

The launcher scripts in this repo are Apache 2.0. The graph engine (graperoot pip package) is proprietary.

The result: your AI spends tokens reasoning, not exploring.

You run: dgc /path/to/project
              ↓
1. Project scanned → semantic graph built (files, symbols, imports)
2. You ask a question
3. Graph identifies the relevant files → packs them into context
4. AI gets your question + the right code already loaded
5. Fewer turns, fewer tokens, better answers

Token savings compound across a session. The graph remembers which files were read, edited, and queried — each turn gets cheaper.

---

Other Tools vs GrapeRoot

Other tools (CodeGraph, code-graph-mcp, and similar) give your AI a graph and let it explore:

You ask a question
  → AI calls search_symbol / get_callers / trace_route
  → AI reads results, decides what else to look up
  → AI calls more tools
  → AI finally has enough context to answer

Your AI spends turns exploring before it can reason.

---

GrapeRoot pre-loads the right context before your AI sees your question:

You ask a question
  → Graph identifies relevant files automatically
  → Files packed into the prompt
  → AI answers immediately

No exploration. No extra tool calls. Your AI starts reasoning from turn one.

---

	Other tools	GrapeRoot
How context is delivered	AI pulls on demand via tool calls	Pre-loaded before every turn
Session memory	No	Yes — compounds across turns
Token budget control	AI decides	Hard-capped per turn
Turns spent exploring	Multiple	Zero
Savings compound	No	Yes — each turn gets cheaper

---

Results

Benchmarked across multiple real-world codebases (7,700+ files) and 50+ engineering prompts:

Metric	Without GrapeRoot	With GrapeRoot
Cost per prompt	$0.49	$0.27
Avg turns per task	11.7	3.5
Avg response time	172s	124s
Quality (scored)	76.6 / 100	86.6 / 100
Cost win rate	—	10 out of 10 prompts

Cost reduction by task type

Task type	Cost reduction
Migration & architecture design	up to 81%
Performance analysis	up to 80%
Testing & test generation	up to 76%
Full-stack debugging	up to 73%
Feature development	up to 71%
Code explanation & audit	up to 55%
Large codebase (7k+ files, avg)	43% average

Savings compound across a session — a token avoided on turn 3 also skips cache re-billing on every subsequent turn. Quality stays equal or improves on every task type above.

Full benchmark methodology and results: graperoot.dev/benchmarks

---

Supported AI Tools

Tool	Command	Status
Claude Code	dgc	✅ Full support
OpenAI Codex CLI	dg	✅ Full support
Cursor	graperoot . --cursor	✅ Full support
Gemini CLI	graperoot . --gemini	✅ Full support
OpenCode	graperoot . --opencode / dgo	✅ Full support
GitHub Copilot	graperoot . --copilot	✅ Full support
OpenClaw	graperoot . --openclaw	✅ Full support
Kilocode	graperoot . --kilocode	✅ Full support
MiMo Code	graperoot . --mimocode	✅ Full support
Antigravity	graperoot . --antigravity	✅ Full support
Kiro CLI	graperoot . --kiro	✅ Full support
Command Code	graperoot . --command-code	✅ Full support

---

Supported Languages

TypeScript · JavaScript · Python · Go · Swift · Rust · Java · Kotlin · Scala · C# · Ruby · PHP

---

Install

macOS / Linux:

curl -sSL https://raw.githubusercontent.com/kunal12203/Codex-CLI-Compact/main/install.sh | bash
source ~/.zshrc   # or ~/.bashrc / ~/.profile

Windows (PowerShell):

irm https://raw.githubusercontent.com/kunal12203/Codex-CLI-Compact/main/install.ps1 | iex

Windows (Scoop):

scoop bucket add dual-graph https://github.com/kunal12203/scoop-dual-graph
scoop install dual-graph

Prerequisites: Python 3.10+, Node.js 18+, and one of the supported AI tools. The installer detects missing tools and offers to install them automatically.

---

Usage

Important: Always use dgc (not claude directly) to ensure the MCP server is running.

Claude Code

dgc                                      # scan current directory, launch Claude
dgc /path/to/project                     # scan a specific project
dgc /path/to/project "fix the login bug" # start with a prompt

OpenAI Codex CLI

dg                              # scan current directory
dg /path/to/project             # scan a specific project
dg /path/to/project "add tests" # start with a prompt

MiniMax

Set MINIMAX_API_KEY, then select either supported model: MiniMax-M3 or MiniMax-M2.7. The minimax alias uses MiniMax-M3.

export MINIMAX_API_KEY="your-api-key"
dg --model=minimax /path/to/project
dg --model=minimax-m3 /path/to/project
dg --model=minimax-m2.7 /path/to/project

MINIMAX_REGION selects the endpoint region and defaults to global_en. MINIMAX_API_MODE selects the compatible API mode and defaults to openai; set it to anthropic to use the Anthropic-compatible endpoint. The launcher uses a 1,000,000-token context window for MiniMax-M3 and a 204,800-token context window for MiniMax-M2.7.

Region	OpenAI-compatible base URL	Anthropic-compatible base URL
global_en	https://api.minimax.io/v1	https://api.minimax.io/anthropic
cn_zh	https://api.minimaxi.com/v1	https://api.minimaxi.com/anthropic

MINIMAX_REGION=cn_zh dg --model=minimax-m3 /path/to/project
MINIMAX_API_MODE=anthropic dgc --model=minimax-m2.7 /path/to/project

Interactive Picker (new in v3.9.99)

graperoot          # shows directory confirm + arrow-key tool picker
graperoot .        # same, picks from current directory
graperoot --version   # print current version
graperoot --update    # force self-update

OpenCode

dgo                             # scan current directory
dgo /path/to/project            # scan a specific project
dgo /path/to/project "refactor" # start with a prompt

All Tools via graperoot

graperoot . --cursor          # Cursor
graperoot . --gemini          # Gemini CLI
graperoot . --opencode        # OpenCode
graperoot . --copilot         # GitHub Copilot
graperoot . --openclaw        # OpenClaw
graperoot . --kilocode        # Kilocode
graperoot . --mimocode        # MiMo Code
graperoot . --kiro            # Kiro CLI
graperoot . --command-code    # Command Code
graperoot /path --gemini "add tests"   # specific project + prompt

Windows

dgc .                          # from inside the project directory
dgc "D:\projects\my-app"       # any drive, any path
dg "C:\work\backend"           # Codex CLI
dgc --gemini "D:\projects\app" # Gemini CLI on Windows

---

How It Works

1. Graph scan — on first run, GrapeRoot extracts files, functions, classes, and import relationships into a local graph stored in .dual-graph/.
2. Context retrieval — each time you ask a question, the graph ranks the most relevant files and packs them into the prompt before your AI sees it.
3. Session memory — files you've read, edited, or queried are weighted higher in future turns. Context compounds.
4. MCP tools — your AI can still drill deeper via graph-aware tools (graph_read, graph_retrieve, graph_neighbors) when it needs to explore.

All processing is local. No code leaves your machine.

---

Data & Files

All data lives in <project>/.dual-graph/ (auto-added to .gitignore):

File	Description
info_graph.json	Semantic graph: files, symbols, edges
chat_action_graph.json	Session memory: reads, edits, queries
context-store.json	Persistent decisions/tasks/facts across sessions

Global install at ~/.dual-graph/:

File	Description
dgc.ps1 / dg.ps1	Launcher scripts (auto-updated)
venv/	Python virtual environment
version.txt	Installed version

---

Configuration

All optional, via environment variables:

Variable	Default	Description
DG_HARD_MAX_READ_CHARS	4000	Max characters per file read
DG_TURN_READ_BUDGET_CHARS	18000	Total read budget per turn
DG_FALLBACK_MAX_CALLS_PER_TURN	1	Max fallback grep calls per turn
DG_RETRIEVE_CACHE_TTL_SEC	900	Retrieval cache TTL (15 min)
DG_MCP_PORT	auto (8080–8099)	Force a specific MCP server port

---

Self-Update

The launcher checks for updates on every run and auto-updates silently. To force an update:

graperoot --update

To disable auto-update (shows a notice instead):

graperoot --no-auto-update

To re-enable:

graperoot --auto-update

Current version: 3.10.19

---

Telemetry

GrapeRoot collects anonymous crash reports to help us fix bugs. What's sent:

• Error type and which step failed (e.g. "scan", "mcp start")
• OS and Python version
• GrapeRoot version

What's never sent: your code, file paths, project names, prompts, or any personal data.

Telemetry is on by default. To opt out:

graperoot --no-telemetry    # disable
graperoot --telemetry       # re-enable

---

Troubleshooting

"MCP Server Connection Failed"

Always use dgc instead of claude directly. dgc starts the MCP server automatically.

# Fix:
claude mcp remove dual-graph
dgc   # re-registers everything

Full troubleshooting guide

See TROUBLESHOOTING.md or graperoot.dev/docs.

---

Contributing

The launcher scripts (bin/) are open source under Apache 2.0. PRs welcome — bug fixes, new AI assistant support, install improvements, docs.

Note: The graph engine (graperoot pip package) is proprietary. The launchers and tooling in this repo are fully open source.

---

Community

Have a question, found a bug, or want to share feedback?

Join the Discord →

---

Star History

---

License

Launcher scripts and tooling in this repository: Apache License 2.0

The graperoot graph engine (PyPI): proprietary. See graperoot.dev.

---