Agent (Claude Code / Codex / Cursor)
  │
  ▼
ContextForge  ←─── single MCP server
  │
  ├─→  codebase-memory-mcp  (graph query: 99% fewer retrieval tokens)
  │           │
  │           ▼
  └─→  headroom             (compression: 60–95% fewer prompt tokens)
            │
            ▼
        LLM Provider

curl -fsSL https://raw.githubusercontent.com/yourusername/contextforge/main/scripts/install.sh | bash

iwr -useb https://raw.githubusercontent.com/yourusername/contextforge/main/scripts/install.ps1 | iex

pip install contextforge
# or with uv (recommended):
uv tool install contextforge

contextforge doctor

✅  Python 3.12
✅  mcp (Model Context Protocol SDK)
✅  headroom-ai
✅  codebase-memory-mcp → /usr/local/bin/codebase-memory-mcp
✅  Everything looks good!

contextforge install --target claude

{
  "mcpServers": {
    "contextforge": {
      "command": "contextforge",
      "args": ["run"]
    }
  }
}

## ContextForge (code intelligence + compression)

When ContextForge MCP tools are available, **always prefer cbm_* tools over
grep/Glob/Read for structural code questions** — they use 99% fewer tokens.

| Instead of...              | Use...                                 |
|----------------------------|-----------------------------------------|
| Grep for a function name   | `cbm_search_graph(name_pattern="...")`  |
| Reading files for call chains | `cbm_trace_path(function_name="...")` |
| Exploring the architecture | `cbm_get_architecture()`                |
| Text search across files   | `cbm_search_code(query="...")`          |

Index first: `cbm_index_repository(repo_path=".")`. After that, all results
pass through headroom compression automatically. Use `cf_stats` to see savings.

cbm_index_repository(repo_path="/path/to/your/project")

# Find all functions matching a pattern
cbm_search_graph(name_pattern=".*Handler.*", label="Function")

# Who calls processPayment?
cbm_trace_path(function_name="processPayment", direction="inbound")

# What would break if I change this?
cbm_get_impact(node_id="<node_id_from_search>")

# High-level architecture view
cbm_get_architecture()

# Full-text search ranked by graph importance
cbm_search_code(query="database connection pool")

# Find unused code
cbm_find_dead_code(confidence="high")

# Compress arbitrary text before including in context
cf_compress(text="<large log output>", hint="logs")

# Session stats
cf_stats()
# → { "tokens_saved": 42183, "overall_compression_ratio": "78%", ... }

# Reset counters for a new session
cf_reset_stats()

contextforge/
├── src/contextforge/
│   ├── __init__.py
│   ├── server.py        # FastMCP server — tool definitions + orchestration
│   ├── cbm_client.py    # stdio JSON-RPC client for the CBM binary
│   ├── compressor.py    # headroom-ai wrapper with per-tool profiles + stats
│   └── cli.py           # typer CLI (run / install / doctor / info)
├── config/
│   └── default.toml     # Default configuration
├── scripts/
│   ├── install.sh        # Linux/macOS quick install
│   └── install.ps1       # Windows PowerShell quick install
├── pyproject.toml
└── README.md