Harness + RTK + Headroom — Three-Layer Synthesis
One-sentence summary: Agent Harness produces the work and guarantees it's correct; RTK and Headroom make that work cheap to feed back into the model — three layers, one thesis (harness > model), built on the same two instincts.
1. They Complement on Two Orthogonal Axes
RELIABILITY axis COST / CONTEXT axis
(what the agent does, (how much its I/O costs)
done correctly)
Agent Harness ████████████████████ ····· (mostly silent)
Headroom ····· ████████████████████
RTK ····· ████████ (shell slice)
- Agent Harness owns reliability: planning, scratch memory, the deterministic verify gate, sandboxed writes, sub-agent delegation. It decides what happens and whether it's correct.
- RTK + Headroom own token economics: they decide how much the context the harness produces and consumes actually costs.
Because these axes are orthogonal, combining them is purely additive — there's no contention. A reliable harness can be expensive; a cheap pipeline can be unreliable. Stacking all three gives you reliable and cheap, and neither side fights the other.
2. The Harness Is the Thing That Feeds RTK and Headroom
This is the concrete coupling, not just thematic overlap. Every rung of the harness emits exactly the content types RTK and Headroom were built to compress:
| Harness project | What it emits into context | Who compresses it |
|---|---|---|
multi_agent_coding EVALUATOR |
pytest output, git/build loop | RTK (native pytest/git filters) |
deep_research_agent |
DuckDuckGo results, RAG chunks, prose synthesis | Headroom (SmartCrusher JSON + Kompress prose) |
harness_ladder eval runner |
structured (model, rung, task, pass/fail) sweeps |
— it's the measurement rig for both |
The harness isn't adjacent to the compression layer — it's the upstream producer. RTK and Headroom sit at the harness's tool-call and message boundary:
Agent Harness (LangGraph) reliability: plan · memory · verify gate · sandbox · sub-agents
│ issues tool calls, accumulates context
▼
Headroom (proxy/wrapper) content layer: SmartCrusher · CodeCompressor · Kompress · CCR · CacheAligner
│ delegates shell output to ↓
RTK shell layer: deterministic per-command filters
▼
LLM provider
3. The Shared Principles — Same Idea Three Times
Once you read all three, the same two design instincts repeat at every layer — which is the real evidence they belong together.
3.1 "Compress by Default, Retrieve on Demand"
- Sub-agent delegation (harness rung 5 / deepagents
task) — isolated context per sub-problem; only the distilled finding returns. Compression at the control-flow level. - Headroom CCR — compress, cache the original,
headroom_retrievewhen needed. Compression at the content level. - RTK tee-on-failure — compress, keep raw in
~/.local/share/rtk/tee/, pull it back on failure. Compression at the shell-output level.
Same principle, three altitudes. The harness's "isolated context window per subagent" is a compression strategy — just one that operates on control flow instead of bytes.
3.2 "Deterministic Gate by Default, LLM/Lossy as Optional Escalation"
- Harness EVALUATOR = pure pytest subprocess, no LLM. The lossy/advisory tier is the
critic-subagent. - RTK = hand-written per-command filters, deterministic, lossless. No escalation tier needed.
- Headroom = rule-based SmartCrusher/CodeCompressor (deterministic) by default; Kompress (ML, lossy) is the optional escalation you enable only under context pressure.
Identical architectural taste: keep the load-bearing path deterministic and auditable; make the probabilistic part opt-in.
4. Integration — Where They Tile, Where They Overlap
4.1 Coverage Map
Agent task
│
├── Shell commands (git, pytest, docker, cargo)
│ ↑ RTK fires here via PreToolUse hook / Hermes plugin
│ Raw: 8,000+ tokens → RTK: ~200 tokens (97%+ savings typical)
│
├── RAG chunks, JSON tool outputs (DuckDuckGo, pgvector)
│ ↑ Headroom SmartCrusher fires here
│ 343 tokens removed per batch in the Headroom experiment
│
├── Prose content, chat history, verbose logs
│ ↑ Headroom Kompress (ML, optional) fires here
│ Enable only when context pressure > ~5,000–15,000 tokens
│
├── Sub-agent context windows
│ ↑ Harness rung 5 / deepagents task: each sub-agent gets isolated window
│ Result returned as distilled text, not accumulated history
│
└── LLM provider
RTK and Headroom tile cleanly — zero overlap:
- RTK = Bash tool calls only
- Headroom = everything else (plus RTK delegation for shell)
- Harness = upstream of both; produces what they compress
4.2 Real Numbers (From These Three Projects)
RTK benchmark (LangGraph + Qwen2.5:7b):
git log --stat -2 8,388 raw → 108 RTK (98.7% savings)
git branch -v 88 raw → 6 RTK (93.2% savings)
git status 66 raw → 22 RTK (66.7% savings)
ls -la 376 raw → 113 RTK (69.9% savings)
────────────────────────────────────────────────────────────
Agent session: 8,592 raw → 231 RTK (97.3% savings)
Headroom experiment (local_first_compression_layer):
Rule-based only (SmartCrusher):
3,496 tokens → 3,174 tokens (9.2% reduction, -4.4% inference time)
With Kompress ML model:
3,496 tokens → 2,600 tokens (25.6% reduction, +35% inference time on CPU)
Break-even: ~5,000–15,000 tokens depending on hardware
5. Watch Points When Combining All Three
5.1 RTK Is Bash-Only
RTK fires on shell tool calls. The deep_research_agent runs on the deepagents virtual filesystem (read_file/write_file) and multi_agent_coding's EVALUATOR uses subprocess — file reads through native tools bypass RTK entirely.
Rule: route dev-loop commands through the shell to get RTK coverage; lean on Headroom (message/content-level) to catch everything RTK can't see.
5.2 Compliance Config Is Constrained
The harness's whole point is a deterministic, auditable gate. Headroom's Kompress is lossy and non-deterministic, which is in tension with that.
Audit-safe stack:
Harness gates (deterministic EVALUATOR)
+ RTK (deterministic, lossless, tee-logged)
+ Headroom rule-based only (kompress_model="disabled")
All three layers deterministic. Nothing inferred. Every original retrievable.
5.3 Local Inference Budget (From deep_research_agent Hands-On)
Qwen3:8b is a reasoning model — it activates extended chain-of-thought on complex delegation tasks, which pushed RAM to 7.77 GB and took 619 seconds for 5 sub-questions. Reducing to 3 sub-questions brought it down to 223 seconds with stable RAM. For production-quality output, cloud models (claude-opus-4-8) are the right call — zero local compute, 3–5× faster. RTK + Headroom matter more on cloud inference (direct cost per token) than local (compute cost, not token cost).
6. The Unbuilt Experiment
harness_ladder's eval runner already emits a structured (model, rung, task, pass/fail) table. Adding a tokens_in / tokens_out / cost_usd axis and running each rung with vs. without the RTK+Headroom stack would turn the complementarity claim into measured numbers.
That experiment would answer two questions neither benchmark currently addresses:
- Does the compression stack affect pass-rate at any rung? (Expected: no, but unverified.)
- What is the per-rung token cost delta when RTK+Headroom is in the pipeline? (Expected: large savings at rung 3+ where the verify loop issues repeated git/pytest commands.)
The eval/runner.py in harness_ladder/ is the right place to wire it.
7. Stack Decision Guide
Dev loop session (Claude Code / Cursor):
RTK alone — install in 2 minutes, zero friction, 93%+ savings on shell output.
Harness + RAG agent (long sessions, multi-agent):
Harness rungs 3–5 + headroom wrap (which brings RTK with it).
SmartCrusher handles JSON, RTK handles shell, Kompress handles prose when needed.
Hermes ambient agent (VPS, background workflows):
Harness pipeline + RTK Hermes plugin (rtk init --agent hermes).
Add Headroom proxy if the agent also reads documents or long context.
RTK matters more here — background agents issue commands without human oversight;
runaway context is a cost control problem, not just a UX one.
Compliance / audit environment:
Harness deterministic EVALUATOR
+ RTK (deterministic, tee-logged)
+ Headroom rule-based only (kompress_model="disabled").
All three layers. Neither introduces non-determinism.