ContextForge

██████╗ ██████╗ ███╗ ██╗████████╗███████╗██╗ ██╗████████╗ ██╔════╝██╔═══██╗████╗ ██║╚══██╔══╝██╔════╝╚██╗██╔╝╚══██╔══╝ ██║ ██║ ██║██╔██╗ ██║ ██║ █████╗ ╚███╔╝ ██║ ██║ ██║ ██║██║╚██╗██║ ██║ ██╔══╝ ██╔██╗ ██║ ╚██████╗╚██████╔╝██║ ╚████║ ██║ ███████╗██╔╝ ██╗ ██║ ╚═════╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═╝ ╚══════╝╚═╝ ╚═╝ ╚═╝ ███████╗ ██████╗ ██████╗ ██████╗ ███████╗ ██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██╔════╝ █████╗ ██║ ██║██████╔╝██║ ███╗█████╗ ██╔══╝ ██║ ██║██╔══██╗██║ ██║██╔══╝ ██║ ╚██████╔╝██║ ██║╚██████╔╝███████╗ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝ Repository-aware execution runtime for Claude Code

Repository graph • Transparent tool execution • Context optimization • Provider agnostic

Problem · What It Does · How It Works · Install · Results · Agents · Architecture · Config · FAQ · Community

---

ContextForge is a local proxy + CLI that sits between Claude Code and your LLM provider — executing repository tool calls locally, compressing context before it reaches the model, and maintaining an AST-level knowledge graph of your codebase. Run local models through Ollama or any major cloud provider. Designed to produce the same result while using significantly fewer tokens on repository-aware tasks.

npm i -g @anuj612/contextforge
cd your-project
cf wrap claude

That's the whole setup. No compilers, no config files, no .env editing — a first-run wizard asks two questions and everything else is automatic.

---

The Problem

AI coding agents waste thousands of tokens on every request:

• Re-reading entire files to find a single function
• Re-discovering repository structure on every edit
• Re-sending large tool schemas and unchanged tool outputs with every turn
• Burning LLM round-trips on file navigation a local index could answer instantly

Result: Slow responses. High API costs. Context window limits hit constantly. And if you run local models, most agent tooling assumes a cloud API and leaves you out entirely.

---

What It Does

• One-command wrapper — cf wrap claude starts the proxy, indexes your repo, launches Claude Code through it, and prints a savings summary when you exit
• Model Context Protocol (MCP) — Exposes ContextForge's native tools directly to Claude Code, Codex, and Gemini CLI through a lightweight stdio bridge (mcp/bridge.js)
• Repository Graph — find_symbol, analyze_impact, find_route — AST-level queries over JS/TS/TSX/Python/Go/Rust/Java that answer without reading files
• Transparent Tool Interception — graph/read/patch tool calls execute locally in the proxy; background tool hops are intercepted by the proxy, avoiding additional client-agent interactions
• Context Optimizer — tool-schema minimization, system-prompt dedup, keep-newest file dedup, AST skeleton compression, junk interception (lockfiles, minified bundles, base64 blobs)
• Surgical patching — contextforge_patch_ast applies edits with AST awareness and returns a unified diff in the result, so the model doesn't re-read files to verify
• Session memory — persistent per-workspace memory store with HNSW vector search, injected as context when relevant
• Live Dashboard — http://localhost:3000/dashboard — token savings, compression ratio, request log in real time
• Doctor — cf doctor diagnoses the whole install in one command; --fix repairs it

---

How It Works (High Level Overview)

  Claude Code            ← launched by `cf wrap claude`
       │   Anthropic-format requests · tools · conversation history
       ▼
  ┌──────────────────────────────────────────────────────────────────┐
  │                  ContextForge  (runs locally)                    │
  ├──────────────────────────────────────────────────────────────────┤
  │                                                                  │
  │    Repository Graph           Transparent Interception           │
  │   AST · symbols · call graph   graph/read/patch run here         │
  │                      │                                           │
  │                      ▼                                           │
  │                Context Optimizer                                 │
  │     Schema minimization · System dedup · Keep-newest dedup       │
  │       AST skeletons · Junk vaulting · History pruning            │
  │                                                                  │
  └──────────────────────────────────────────────────────────────────┘
       │   compressed payload — substantially smaller in real sessions
       ▼
  LLM Provider  (Ollama · Anthropic · OpenAI · Groq · Gemini)

1. cf wrap claude ensures the environment (models, native engine), starts the proxy, indexes your repo (a 30-file Express app indexes in ~0.5s), and launches Claude Code with the proxy as its base URL plus ContextForge's MCP tools registered.
2. Requests are translated between Anthropic format (what Claude Code speaks) and your upstream provider's format — this is how Claude Code drives local Ollama models.
3. Repository navigation and ContextForge-specific tools execute locally. find_symbol('deleteFile') returns file + line range from the pre-built graph — no file reads, no wasted round-trip.
4. The optimizer compresses what's left — schemas, duplicate history, oversized junk — with age-gating so content the model just requested is never compressed out from under it.
5. On exit, you get the receipt: ✔ Session: 14 requests · 424,129 tokens in → 208,163 sent · 50.9% saved (est).

---

Quick Start

Option A: npm (recommended)

Requires Node ≥ 20. No compilers — prebuilt native binaries ship for Windows, macOS (Intel/ARM), and Linux (x64/ARM).

npm i -g @anuj612/contextforge
cd your-project
cf wrap claude

First run: a wizard asks for your upstream provider (Ollama/Anthropic/OpenAI/Groq/Gemini) and model, then auto-downloads the embedding model (~23MB, SHA-256 verified). Subsequent runs go straight to work.

cf doctor        # 8-point install diagnosis — run this if anything misbehaves

Option B: From source (contributors / unsupported platforms)

git clone https://github.com/anujkushwaha612/ContextForge.git
cd ContextForge
npm install
bash scripts/vendor-grammars.sh    # pinned tree-sitter grammars
bash scripts/setup-onnx.sh         # embedding model (or let `cf setup` do it)
npm run build:native               # requires Python 3 + C++ toolchain
npm link                           # makes `cf` available globally
cf doctor

---

Use With Your AI Agent

Claude Code (fully supported)

cd your-project
cf wrap claude                     # everything automatic
cf wrap claude -- --continue       # pass args through to Claude after --

cf wrap automatically configures the proxy, injects ANTHROPIC_BASE_URL, registers ContextForge's MCP tools for the session, and cleans everything up when Claude exits. Your Claude Code configuration is never permanently modified.

Prefer managing the proxy yourself?

cf start                           # start the proxy in the background
cf mcp install                     # persistent MCP registration
claude                             # launch Claude however you like
cf stop

Useful commands:

cf status
cf logs -f
cf restart
cf mcp status

---

Codex & Gemini CLI (experimental)

ContextForge also supports persistent MCP registration for Codex and Gemini CLI via:

cf mcp install

Basic compatibility is implemented, but these integrations have not yet received the same level of real-world testing as Claude Code.

If you use Codex or Gemini CLI with ContextForge, we'd greatly appreciate bug reports, compatibility feedback, and feature requests.

---

Real Results

> Note: The following is a real-world case study. A comprehensive automated test suite and official benchmark runs against standardized AI evaluation suites (like SWE-bench) are currently in development.

The same Soft-Delete feature was implemented twice in the same Express.js cloud storage backend using the same model (local Ollama), same repository state, and same instructions.

Head-to-head Comparison

| Metric | Passthrough Mode | ContextForge Mode | Difference | | ---------------------------------- | ------------------------------------: | ---------------------------------------------: | ----------------: | | LLM round-trips | 41 | 14 | 66% fewer | | Input tokens | 1,632,266 | 444,092 | 72.8% fewer | | Output tokens | 1,632,266 | 384,033 | 76.5% fewer | | Session-reported token savings | — | 60,059 (13.5%) | — | | Repository exploration | Full-file reads and repeated searches | Graph-guided symbol lookup with targeted reads | More targeted | | Task management | 6 TaskCreate/TaskUpdate operations | None | Lower overhead | | Final implementation | ✅ Correct | ✅ Correct | Equivalent output |

---

Implementation Comparison

To compare the two approaches, I implemented the same Soft-Delete feature in the cloud storage backend repository using both ContextForge Mode and Passthrough Mode, with each run starting from the exact same initial repository state.

• Repository: https://github.com/anujkushwaha612/ADrive_backend

ContextForge Mode

• Commit: https://github.com/anujkushwaha612/ADrive_backend/commit/e78700d5cb15b130df85f728772785bd88d5b413
• Run Statistics: 14 requests · ~444k input tokens

Passthrough Mode

• Commit: https://github.com/anujkushwaha612/ADrive_backend/commit/0f912bfb00b805882b1154a136520d6edecc3a9d
• Run Statistics: 41 requests · ~1.63M input tokens

---

Understanding the Metrics

At first glance, two numbers appear contradictory:

• 72.8% fewer input tokens compared to Passthrough Mode.
• 13.5% session-reported token savings reported by ContextForge.

These measure different things.

Workflow Savings

The 72.8% reduction comes from comparing the two complete executions.

ContextForge changes how the model interacts with the repository:

• Uses graph-based symbol lookup instead of repeated repository exploration.
• Performs targeted line-range reads instead of repeatedly reading entire files.
• Reduces unnecessary tool calls and repeated verification.
• Reaches the same implementation in 14 requests instead of 41.

These are workflow savings: tokens that were never generated because the tooling changed the workflow and the task was solved more efficiently.

Since those requests never happened, they cannot be counted by an in-session compression tracker.

Session Compression

The 13.5% figure is the amount of prompt text removed within the ContextForge session itself.

This metric measures how much prompt content ContextForge compressed or eliminated before forwarding requests to the model. It does not compare against an external Passthrough run.

In other words:

• 72.8% answers: "How much smaller was this entire implementation compared to Passthrough?"
• 13.5% answers: "How much prompt content did ContextForge remove from the requests that were actually sent?"

These metrics are complementary rather than contradictory.

Notes

• Session-level compression depends on conversation length. Short sessions naturally provide less opportunity for compression than long-running coding sessions.
• Token counts are estimated using cl100k tokenization, so absolute values are approximate.
• The implementation produced by both runs was functionally equivalent; the primary differences were repository navigation strategy, request count, and token consumption.

---

When to Use · When to Skip

Great fit if you…

• Run Claude Code daily against a real codebase — especially through local Ollama models, which ContextForge makes a first-class Claude Code backend
• Hit context window limits on multi-file tasks — rename, refactor, audit, search
• Want token savings without changing your agent, your prompts, or your code
• Want AST-aware graph queries and surgical patching instead of read-the-whole-file loops

Skip it if you…

• Only send short, single-turn prompts — the pipeline pays off from turn 2 onward
• Work in a sandboxed environment where local processes and file watchers cannot run
• Need a hosted or cloud-managed solution — ContextForge is local-first by design

---

Architecture

┌─────────────────┐
│  AI Agent       │  Claude Code (v1) · MCP: Codex, Gemini CLI
│  (Client)       │
└────────┬────────┘
         │ Anthropic-format request        ┌──────────────────────────┐
         ↓                                 │  cf CLI                  │
┌───────────────────────────────────────┐  │  wrap · doctor · config  │
│           ContextForge Proxy          │◄─┤  start/stop · mcp · init │
│                                       │  └──────────────────────────┘
│  ┌─────────────────────────────────┐  │
│  │   Repository Graph              │  │  SQLite graph: symbols, calls,
│  │    (Tree-sitter AST + HNSW)     │  │  imports, routes + vector index
│  └─────────────────────────────────┘  │
│  ┌─────────────────────────────────┐  │
│  │   Execution Engine              │  │  graph/read/patch tools run
│  │    (Transparent Interception)   │  │  locally; patches return diffs
│  └─────────────────────────────────┘  │
│  ┌─────────────────────────────────┐  │
│  │   Context Optimizer             │  │  pressure-aware, age-gated
│  │    (Compression Pipeline)       │  │  compression + dedup + vaulting
│  └─────────────────────────────────┘  │
│  ┌─────────────────────────────────┐  │
│  │   Memory (per-workspace)        │  │  persistent HNSW + SQLite
│  └─────────────────────────────────┘  │
└────────┬──────────────────────────────┘
         │ translated + compressed request
         ↓
┌─────────────────┐
│  LLM Provider   │  Ollama · Anthropic · OpenAI
└─────────────────┘

What's inside

• Repository Graph — Tree-sitter AST parsing for JavaScript, TypeScript, TSX, Python, Go, Rust, Java (pinned grammar versions, compiled into a native N-API addon). Indexes functions, classes, imports/exports, call edges, HTTP routes, string literals, and env-var references into SQLite, plus a symbol-level HNSW vector index for semantic lookup. Automatically refreshed after patches and filesystem changes.
• Model Context Protocol (MCP) Bridge — ContextForge integrates with agents using the open MCP standard. The mcp/bridge.js script acts as a high-performance, lightweight stdio bridge that dynamically fetches tool definitions from the proxy and forwards execution requests. This keeps the client integration entirely decoupled from the heavy AST graph engine.
• Transparent Tool Interception — contextforge_query_graph, read_file_chunk, contextforge_patch_ast, and contextforge_retrieve execute inside the proxy. Background tool hops are intercepted by the proxy, avoiding additional client-agent interactions.
• Tool Schema Minimization — ContextForge truncates non-critical descriptions semantically (never its own tools' instructions) and caches the result.
• Keep-newest Deduplication — when the same file appears multiple times in history, older copies become

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: anujkushwaha612
• Source: anujkushwaha612/ContextForge
• License: MIT
• Homepage: https://github.com/anujkushwaha612/ContextForge#real-results

Install and usage instructions live in the source repository linked above.