GrapeRoot

June 11, 2026 · View on GitHub

graperoot.dev · Docs · Benchmarks · Pro · Discord · Troubleshooting

A context engine that makes Claude Code, Codex CLI, Gemini CLI, Cursor, OpenCode, and GitHub Copilot 30-45% cheaper without sacrificing quality. It builds a semantic graph of your codebase and pre-loads the right files into every prompt — so your AI spends tokens reasoning, not exploring.

Works on macOS, Linux, and Windows. Supports any project size.

Supports TypeScript, JavaScript, Python, Go, Swift, Rust, Java, Kotlin, C#, Ruby, and PHP.

Join the community: discord.com/invite/YwKdQATY2d

How It Works

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. Claude 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.

Results

Benchmarked across 80+ prompts (5 complexity levels) on a real-world full-stack app. Full results at graperoot.dev/benchmarks.

MetricWithout Dual-GraphWith Dual-Graph
Avg cost per prompt$0.46$0.27
Avg turns16.810.3
Avg response time186s134s
Quality (regex scorer)82.7/10087.1/100

Cost wins on 16 out of 20 prompts. Quality equal or better on all complexity levels.

Install

Full setup guide at graperoot.dev/setup.

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+, Claude Code or Codex CLI. The installer detects missing tools and offers to install them via winget (Windows) or homebrew (macOS).

Usage

⚠️ Important: Always use dgc (not claude directly) to ensure the MCP server is running. Running claude alone will result in "MCP Server Connection Failed" errors.

Claude Code (dgc)

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

Codex CLI (dg)

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

Other AI Assistants (graperoot)

You can also use the graperoot command directly with any supported assistant:

graperoot .                      # current directory, default (Claude)
graperoot . --cursor             # Cursor
graperoot . --gemini             # Gemini CLI
graperoot . --opencode           # OpenCode
graperoot . --copilot            # GitHub Copilot
graperoot . --antigravity        # Google Antigravity
graperoot . --codex              # Codex CLI
graperoot /path/to/project --cursor           # specific project
graperoot /path/to/project --gemini "add tests"  # with a prompt

Or via the dgc / dg aliases with an assistant flag:

dgc --gemini /path/to/project    # Gemini CLI
dgc --cursor /path/to/project    # Cursor
dgc --opencode /path/to/project  # OpenCode
dgc --copilot /path/to/project   # GitHub Copilot

Typo detection is built in — --claud or --gemi will suggest the correct flag instead of silently failing.

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

What It Does Under the Hood

  1. Scans your project — extracts files, functions, classes, import relationships into a local graph. Supports TS/JS, Python, Go, Swift, Rust, Java, Kotlin, C#, Ruby, and PHP.
  2. Pre-loads context — when you ask a question, the graph ranks relevant files and packs them into the prompt before Claude sees it. No extra tool calls needed.
  3. Remembers across turns — files you've read or edited are prioritized in future turns. Context compounds.
  4. MCP tools available — Claude can still explore the codebase via graph-aware tools (graph_read, graph_retrieve, graph_neighbors, etc.) when it needs to go deeper.

All processing is local. No code leaves your machine.

Data & Files

All data lives in <project>/.dual-graph/ (gitignored automatically).

FileDescription
info_graph.jsonSemantic graph of the project: files, symbols, edges
chat_action_graph.jsonSession memory: reads, edits, queries, decisions
context-store.jsonPersistent store for decisions/tasks/facts across sessions
mcp_server.logMCP server logs

Global files in ~/.dual-graph/:

FileDescription
dgc.ps1 / dg.ps1Launcher scripts (auto-updated)
venv/Python virtual environment for dependencies
version.txtCurrent installed version

Configuration

All optional, via environment variables:

VariableDefaultDescription
DG_HARD_MAX_READ_CHARS4000Max characters per file read
DG_TURN_READ_BUDGET_CHARS18000Total read budget per turn
DG_FALLBACK_MAX_CALLS_PER_TURN1Max fallback grep calls per turn
DG_RETRIEVE_CACHE_TTL_SEC900Retrieval cache TTL (15 min)
DG_MCP_PORTauto (8080-8099)Force a specific MCP server port

Context Store

Decisions, tasks, and facts from your sessions are persisted in .dual-graph/context-store.json and re-injected at the start of the next session. This gives Claude continuity across conversations.

You can also create a CONTEXT.md in your project root for free-form session notes.

Token Tracking

A token-counter dashboard is registered automatically with Claude Code:

http://localhost:8899

Usage from inside a Claude session:

count_tokens({text: "<content>"})   # estimate tokens before reading
get_session_stats()                  # running session cost

Self-Update

The launcher checks for updates on every run and auto-updates if a new version is available. No manual intervention needed.

Current version: 3.9.96

Troubleshooting

"MCP Server Connection Failed" or "HTTP 404: Not Found"

Cause: The dual-graph MCP server isn't running. This happens when running claude directly instead of through dgc.

Solution: Always use dgc instead of claude:

# ❌ Don't run:
claude

# ✅ Run this:
dgc
dgc /path/to/project

The dgc launcher automatically starts the MCP server and registers it with Claude Code.

If the error persists:

  1. Clean up stale configs:

    claude mcp remove dual-graph
claude mcp remove token-counter --scope user

  2. Run dgc again (it will re-register automatically):

    dgc

  3. Check if the server started:

    # Verify MCP server is running:
lsof -i :8080-8099 | grep python

# Check logs:
cat .dual-graph/run/claude/mcp_server.log

  4. Fresh install (if nothing else works):

    rm -rf ~/.dual-graph
claude mcp remove dual-graph 2>/dev/null
curl -sSL https://raw.githubusercontent.com/kunal12203/Codex-CLI-Compact/main/install.sh | bash
source ~/.zshrc  # or ~/.bashrc

MCP Server Won't Start

Check the logs:

cat .dual-graph/run/claude/mcp_server.log

Common issues:

  • Port already in use: Set a custom port with DG_MCP_PORT=8090 dgc
  • Python dependencies missing: Re-run installer or pip install graperoot mcp uvicorn --upgrade
  • Permission errors: Check file permissions in .dual-graph/

Session-Specific Issues

Resume not working? The MCP server is session-based — it stops when you exit. To resume with dual-graph:

dgc --resume <session-id>

Context not persisting? Check if .dual-graph/context-store.json exists and is writable.

Privacy & Security

  • All project data stays local. Graphs, session data, and code never leave your machine.
  • The only outbound calls are:
    • Version check — fetches a version string (no project data).
    • Heartbeat — sends a random install ID and platform only. No hardware fingerprinting, no file names, no code.
    • One-time feedback — optional rating after first day of use.
  • .dual-graph/ is automatically added to .gitignore.

Uninstall

macOS / Linux:

rm -rf ~/.dual-graph
sed -i.bak '/\.dual-graph/d' ~/.zshrc ~/.bashrc 2>/dev/null
rm -rf .dual-graph .claude/settings.local.json
claude mcp remove token-counter --scope user 2>/dev/null
claude mcp remove dual-graph 2>/dev/null
rm -rf ~/.claude/token-counter
rm -f ~/.claude/token-counter-stop.sh

Windows (PowerShell):

Remove-Item "$env:USERPROFILE\.dual-graph" -Recurse -Force -ErrorAction SilentlyContinue
$p = [Environment]::GetEnvironmentVariable("PATH","User") -split ";" | Where-Object { $_ -notlike "*\.dual-graph*" }
[Environment]::SetEnvironmentVariable("PATH", ($p -join ";"), "User")
Remove-Item ".dual-graph" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item ".claude\settings.local.json" -Force -ErrorAction SilentlyContinue
claude mcp remove token-counter --scope user 2>$null
claude mcp remove dual-graph 2>$null
Remove-Item "$env:USERPROFILE\.claude\token-counter" -Recurse -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.claude\token-counter-stop.ps1" -Force -ErrorAction SilentlyContinue

The PATH/project commands remove the global install. Run the project-local commands inside each project you used dual-graph with.

Contributing

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

Note: The graph engine (graperoot) is a separate proprietary component distributed via PyPI. The launcher scripts and tooling in this repo are fully open source; the core graph intelligence is not. See graperoot.dev/graperoot-pro for Pro features.

Community

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

Join the Discord: discord.com/invite/YwKdQATY2d

  • Get help with setup
  • Report bugs
  • Share workflows
  • Follow releases

Acknowledgements

A huge thank you to everyone who used early versions of Dual-Graph and shared feedback through the telemetry program — your usage data helped us squash bugs and stabilize the tool into what it is today. We've now removed all telemetry in favor of full transparency.

Want to keep helping shape the project? Join the Discord or visit graperoot.dev.

Star History

Star History Chart

License

The launcher scripts and tooling in this repository are licensed under the Apache License 2.0.

The graperoot graph engine (installed as a PyPI dependency) is proprietary and not covered by this license.