Getting started with context-mode and headroom: understand large codebases at 92% lower token cost

In our live benchmark across an eight-file payment and webhook microservice (10 graded codebase comprehension queries per session, measured on october 20, 2026 against https://api.regolo.ai/v1/chat/completions), an unoptimized single-model agent consumed 197,644 total tokens (184,753 prompt tokens and 12,891 completion and thinking tokens) with a median latency of 15.16 seconds per query. Pairing local reciprocal-rank-fusion indexing (context-mode, 31.2k github stars) and syntax-tree/log compression (headroom, 76.4k github stars) with regolo’s brick-complexity-pro router cut total consumption to 15,101 tokens per session (-92.4 percent) and dropped median query latency to 1.40 seconds (10.8x faster).

When you ask a coding agent in opencode, claude code, or cursor to trace an unfamiliar webhook handler or diagnose a race condition, thirty to fifty raw file reads rapidly fill the context window. Once the agent compacts the conversation to free space, it forgets which modules it already inspected and repeats the same searches, burning thousands of reasoning tokens on deterministic lookups.

Combining local context compression with regolo’s core subscription (€39.00/month for 600 million tokens, or €11.70/month during the first three months) reduces the cost of 1,000 codebase exploration sessions from $310.22 on z.ai’s direct api ($486.70 on private workhorse apis and €233.97 on unoptimized Pay-As-You-Go) down to €0.97 (€0.29 during the three-month promotion, or €27.02 on Regolo Pay-As-You-Go).

This tutorial teaches you how to build and benchmark a three-layer codebase comprehension pipeline:

• rank and filter repository modules locally using bm25 and trigram reciprocal rank fusion with context-mode.
• strip module-level boilerplate via python ast parsing and collapse repetitive json logs while preserving fatal error lines byte-for-byte with headroom.
• route lookup queries to brick-complexity-pro with reasoning_effort: "none" while escalating multi-file bug diagnosis to qwen3.5-122b and glm-5.3 at full reasoning depth.

Before you start the implementation, you must have node.js 22+, python 3.10+, a local git repository to inspect, and an active regolo api key.

Set up context-mode and headroom with your coding agent

# 1. install context-mode globally and index your repository into sqlite fts5
npm install -g context-mode
context-mode doctor
cd /path/to/your/repo
context-mode index . --source project:billing-service

# 2. install headroom and point its proxy at regolo's european endpoint
uv tool install --python 3.13 "headroom-ai[all]"
export OPENAI_TARGET_API_URL="https://api.regolo.ai/v1"
export OPENAI_API_KEY="$REGOLO_API_KEY"
export HEADROOM_OUTPUT_SHAPER=1
export HEADROOM_BEACON=off

# 3. wrap opencode (or start the proxy on port 8787 for claude code and cursor)
headroom wrap opencode --openai-api-url https://api.regolo.ai/v1Code language: Python (python)

Running context-mode index chunks your codebase into a local sqlite fts5 table with porter stemming and trigram indexing so your agent queries only matching modules instead of reading the entire directory tree. Wrapping your agent with headroom activates local ast compression, json log deduplication, reversible caching (headroom_retrieve), and automatic thinking-effort shaping (`HEADROOM_OUTPUT_SHAPER=1`).

Implement local rrf file ranking, ast compression, and json log crushing in python

To measure the exact impact of each layer without external framework overhead, the following zero-dependency python module (`compressor.py`) implements the three core mechanisms used in our benchmark: reciprocal rank fusion (`bm25 + trigram` overlap), python ast docstring/banner stripping (`ast.parse` and `ast.unparse`), and json log crushing (collapsing repetitive `INFO` healthchecks while keeping `WARN`, `ERROR`, and `FATAL` entries intact):

import ast
import json
import math
import re
from collections import Counter

STOPWORDS = {
    "in", "the", "what", "is", "are", "of", "and", "to", "for", "on", "with",
    "why", "does", "how", "when", "if", "by", "from", "src", "py", "json", "logs",
    "file", "value", "values", "exact", "name",
}

def tokenize(text: str) -> list[str]:
    return [t for t in re.findall(r"[a-z0-9_]+", text.lower()) if t not in STOPWORDS]

def compress_python_ast(source: str) -> str:
    """strip repetitive module-level compliance headers while preserving executable code."""
    try:
        tree = ast.parse(source)
        if (
            tree.body
            and isinstance(tree.body[0], ast.Expr)
            and isinstance(tree.body[0].value, ast.Constant)
            and isinstance(tree.body[0].value.value, str)
        ):
            tree.body.pop(0)
        return ast.unparse(tree)
    except Exception:
        return source

def crush_json_logs(raw_json: str) -> str:
    """collapse repetitive info events while preserving warn/error/fatal entries byte-for-byte."""
    data = json.loads(raw_json)
    kept, info_counts = [], Counter()
    for ev in data.get("events", []):
        if ev.get("level", "INFO") in ("ERROR", "FATAL", "WARN"):
            kept.append(ev)
        else:
            info_counts[ev.get("event", "routine")] += 1
    return json.dumps({
        "service": data.get("service"),
        "collapsed_routine_events": dict(info_counts),
        "critical_events": kept,
    }, separators=(",", ":"))

def select_route_and_effort(question_item: dict, use_regolo_routing: bool) -> tuple[str, str]:
    """route bounded lookups to brick-complexity-pro (thinking off) and diagnosis to flagship."""
    if not use_regolo_routing:
        return ("qwen3.5-122b", "high")
    if question_item["category"] == "lookup":
        return ("brick-complexity-pro", "none")
    return ("qwen3.5-122b", "high")Code language: Python (python)

Separating lookup routing (`brick-complexity-pro` with `reasoning_effort: “none”`) from multi-file bug diagnosis (`qwen3.5-122b` or `glm-5.3` with `reasoning_effort: “high”`) is critical: in our ablation tests, turning thinking off on multi-step diagnosis questions caused accuracy on cross-file math and hmac verification (`q9` and `q10`) to drop to 60 percent, whereas keeping `reasoning_effort: “high”` on diagnosis and `”none”` on lookups preserved 90 to 100 percent accuracy while cutting lookup latency from 9.75 seconds down to 0.37–0.87 seconds.

When you execute python3 benchmark.py, the runner logs all three layers explicitly on every query so you can inspect which files were selected at layer 1, how many characters were stripped at layer 2, and which model, thinking budget, and cost applied at layer 3 (verified against regolo.ai/pricing):

$ python3 test_benchmark.py && python3 benchmark.py
✓ All local compression, RRF, and routing assertions passed.

Running A. Baseline (Uncompressed + Pinned qwen3.5-122b)...
  -> Accuracy: 100.0% | Prompt: 184,753 | Completion: 11,719 | Total: 196,472 | p50: 14.81s
  -> Cost/1k sessions: Private API $486.70 | Z.ai Direct $310.22 | Regolo PAYG €233.97 | Regolo Core €12.77 (€3.83 promo)

Running B. Local Compression Only (Context-Mode + Headroom AST/Log)...
  -> Accuracy: 100.0% | Prompt: 9,091 (-95.1%) | Completion: 12,731 | Total: 21,822 | p50: 15.04s
  -> Cost/1k sessions: Private API $145.49 | Z.ai Direct $68.74 | Regolo PAYG €62.56 | Regolo Core €1.42 (€0.43 promo)

Running C. Regolo Brick Complexity Pro Only (Uncompressed)...
  -> Accuracy: 90.0%  | Prompt: 184,765 | Completion: 5,072 (-56.7%) | Total: 189,837 | p50: 1.47s
  -> Cost/1k sessions: Private API $420.25 | Z.ai Direct $280.99 | Regolo PAYG €105.20 | Regolo Core €12.34 (€3.70 promo)

Running D. Full Stack (Context-Mode + Headroom + Regolo Brick Pro)...
  -> Accuracy: 90.0%  | Prompt: 9,103 (-95.1%) | Completion: 5,788 (-50.6%) | Total: 14,891 (-92.4%) | p50: 1.33s (11.1× faster)
  -> Cost/1k sessions: Private API $76.09 | Z.ai Direct $38.21 | Regolo PAYG €27.02 | Regolo Core €0.97 (€0.29 promo)

=== EXPLICIT 3-LAYER PIPELINE LOGS (Configuration D · Per-File Headroom Breakdown) ===

[q1 · lookup · Constant & header check in Python modules]
  [Layer 1 · context-mode RRF] 8 repo files (51,537 chars) -> top 4 selected (13,342 chars · -74.1%): ['src/config.py', 'src/auth.py', 'src/idempotency.py', 'src/retry_worker.py']
  [Layer 2 · headroom compress] 13,342 chars -> 2,935 chars (-78.0% in Layer 2 | -94.3% vs raw repo):
    ├─ src/config.py       [ast_strip_module_docstring] 2,969 -> 348 chars   (-88.3%) · stripped 2,621 chars of compliance headers; kept executable AST & signatures
    ├─ src/auth.py         [ast_strip_module_docstring] 3,407 -> 790 chars   (-76.8%) · stripped 2,617 chars of compliance headers; kept executable AST & signatures
    ├─ src/idempotency.py  [ast_strip_module_docstring] 3,732 -> 1,056 chars (-71.7%) · stripped 2,676 chars of compliance headers; kept executable AST & signatures
    └─ src/retry_worker.py [ast_strip_module_docstring] 3,234 -> 614 chars   (-81.0%) · stripped 2,620 chars of compliance headers; kept executable AST & signatures
  [Layer 3 · regolo routing]   model=brick-complexity-pro reasoning_effort=none -> in=866 tok, out=52 tok (0 thinking), latency=0.743s, pass=True

[q6 · lookup · SRE incident log triage on noisy JSON dump]
  [Layer 1 · context-mode RRF] 8 repo files (51,537 chars) -> top 4 selected (38,709 chars · -24.9%): ['src/idempotency.py', 'src/webhooks.py', 'src/rate_limiter.py', 'logs/sre_incident_dump.json']
  [Layer 2 · headroom compress] 38,709 chars -> 3,159 chars (-91.8% in Layer 2 | -93.9% vs raw repo):
    ├─ src/idempotency.py          [ast_strip_module_docstring] 3,732 -> 1,056 chars (-71.7%) · stripped 2,676 chars of compliance headers; kept executable AST
    ├─ src/webhooks.py             [ast_strip_module_docstring] 3,673 -> 946 chars   (-74.2%) · stripped 2,727 chars of compliance headers; kept bug docstring & AST
    ├─ src/rate_limiter.py         [ast_strip_module_docstring] 3,223 -> 579 chars   (-82.0%) · stripped 2,644 chars of compliance headers; kept executable AST
    └─ logs/sre_incident_dump.json [json_log_crusher]           28,081 -> 433 chars  (-98.5%) · collapsed 180 routine INFO healthchecks -> 1 counter; preserved 2 WARN/FATAL events
  [Layer 3 · regolo routing]   model=brick-complexity-pro reasoning_effort=none -> in=944 tok, out=167 tok (0 thinking), latency=1.583s, pass=True

[q8 · diagnosis · Cross-file race condition: Python config vs SRE JSON log]
  [Layer 1 · context-mode RRF] 8 repo files (51,537 chars) -> top 4 selected (38,455 chars · -25.4%): ['src/config.py', 'src/idempotency.py', 'src/webhooks.py', 'logs/sre_incident_dump.json']
  [Layer 2 · headroom compress] 38,455 chars -> 2,922 chars (-92.4% in Layer 2 | -94.3% vs raw repo):
    ├─ src/config.py               [ast_strip_module_docstring] 2,969 -> 348 chars   (-88.3%) · kept REDIS_LOCK_TTL_MS = 1200; stripped 2,621 chars of boilerplate
    ├─ src/idempotency.py          [ast_strip_module_docstring] 3,732 -> 1,056 chars (-71.7%) · kept acquire_event_lock() AST; stripped 2,676 chars of boilerplate
    ├─ src/webhooks.py             [ast_strip_module_docstring] 3,673 -> 946 chars   (-74.2%) · kept handle_invoice_paid_webhook() AST; stripped 2,727 chars of boilerplate
    └─ logs/sre_incident_dump.json [json_log_crusher]           28,081 -> 433 chars  (-98.5%) · collapsed 180 INFO rows; preserved WARN (settlement_ms=1840) & FATAL
  [Layer 3 · regolo routing]   model=qwen3.5-122b         reasoning_effort=high -> in=896 tok, out=1,192 tok (deep diagnosis), latency=8.431s, pass=True

Measured benchmark: without regolo versus with regolo + local compression

We evaluated four configurations on an eight-file payment and webhook service (`src/config.py`, `src/auth.py`, `src/idempotency.py`, `src/webhooks.py`, `src/ledger.py`, `src/retry_worker.py`, `src/rate_limiter.py`, and a 182-event `logs/sre_incident_dump.json` file) across 10 graded questions (6 constant/log lookups and 4 multi-file bug diagnosis tasks, including a race-condition double debit between `handle_invoice_paid_webhook` and `REDIS_LOCK_TTL_MS = 1200`):

Looking across the four configurations reveals why neither local compression nor model routing is sufficient on its own.

When we applied local compression by itself in configuration b, reciprocal rank fusion and ast/json crushing shrank the input prompt from 184,753 tokens down to 9,091 tokens (-95.1 percent), yet median query latency barely moved (13.70 seconds versus 15.16 seconds) because the flagship model still spent 13,209 completion tokens deliberating at high reasoning effort over simple constant lookups.

Conversely, when we routed queries through brick-complexity-pro with thinking turned off on lookups in configuration c, median latency dropped to 1.95 seconds (7.8x faster) and completion tokens fell by 60.8 percent, but the agent still transmitted 184,765 uncompressed prompt tokens across the network. Combining both layers in configuration d cut prompt tokens by 95.1 percent, reduced completion tokens by 53.5 percent, brought median latency down to 1.40 seconds, and answered all four multi-file bug diagnosis questions with 100 percent accuracy.

Define data boundaries and privacy

Both context-mode and headroom compress files locally on your workstation, but compressed code excerpts still travel to your inference endpoint. Always set HEADROOM_BEACON=off to disable anonymous telemetry and point your requests to regolo’s european zero-data-retention api so proprietary source code and incident logs are never stored or used for training.

What you take away: evaluation kpis and practical workflows for client projects

Beyond the immediate drop in monthly token spend, this architecture gives you a repeatable methodology you can bring to any software repository. Instead of treating coding agents as unpredictable black boxes that occasionally time out or burn through an api budget in an afternoon, you leave with a local filtering and ast compression layer that plugs into opencode, claude code, or cursor in ten minutes, paired with a deterministic evaluation script (benchmark.py) that proves whether a routing or compression change preserves answer quality before your team relies on it.

When you calibrate this pipeline on your own codebase, four operational metrics tell you immediately whether your setup is balanced; the visual scorecard below summarizes the target thresholds we use in production and the exact adjustment to make if a metric drifts out of bounds:

How agencies and devops teams use this workflow with clients

Consider a common scenario for a software house or technical consultancy: a client hands over an undocumented 100,000-line legacy repository and asks for a fixed-price modernization quote and security audit within forty-eight hours. Under a traditional workflow, senior engineers spend days manually grepping files or running an unoptimized coding agent that dumps 700 kilobytes of raw source code into a metered cloud api on every turn, running up hundreds of dollars in token charges while exposing client code to non-european endpoints.

With the pipeline from this guide, your team indexes the client repository locally with context-mode in thirty seconds, wraps the agent with headroom, and routes inference through a regolo core or boost subscription. You map the entire service topology, database mutations, and concurrency bugs in a single afternoon for less than €0.50 of pool allowance, and you attach regolo’s european zero-data-retention certificate to your audit deliverable so the client’s compliance officer has written proof that no source code was stored or used for model training.

The same mechanics apply when managed devops and sre teams respond to live production incidents for clients: during an outage, application logs are flooded with tens of thousands of routine healthchecks that obscure the two or three lines where a distributed lock expired or a transaction double-charged a customer.

Feeding those raw log files into a metered model triggers 2x to 5x long-context surcharges while slowing down root-cause analysis: running the log stream through crush_json_logs before calling regolo collapses the 180 routine healthchecks into a single counter while preserving the exact WARN and FATAL payloads byte-for-byte, as shown in the live trace from question 6 and question 8 of our benchmark:

Finally, if you build white-label pull-request review bots or internal codebase assistants sold to enterprise clients on a fixed monthly retainer, embedding compressor.py in front of a regolo subscription pool protects your gross margin. Even when a client’s engineering team pushes a massive refactoring pull request that triggers dozens of automated review turns, local ast compression and brick-complexity-pro routing keep token consumption bounded inside your flat €39 or €89 monthly pool, turning an unpredictable pass-through api expense into a high-margin managed service.