Headroom vs RTK: the smaller output wasn't always the better answer

The obvious way to compare Headroom and RTK is to ask which one removes more tokens. That question produced the least useful answer in the controlled test.

RTK was dramatically more aggressive on two verbose logs and one structured JSON payload. Headroom reduced less, passed some inputs through untouched, and required a materially heavier warmed setup before its text compressor did real work. Yet the smallest output was not consistently the most actionable one. On a nested JSON failure, RTK retained none of the four facts designated as necessary for the next move. On a mixed failure log, both tools dropped the exact failing test name and the complete recovery command from the first response.

The practical distinction is a recovery contract. RTK is a compact, command-aware CLI layer. Headroom is a broader context-compression system with an explicit compress-cache-retrieve path. Choose between them by the output grammar you know, the evidence you cannot afford to lose, and what a second read costs—not by a repository percentage.

The verdict

Use case	Better starting point	Why	Boundary
Familiar developer commands with predictable summaries	RTK	One verified binary and very aggressive command-specific filtering	Inspect what each filter retains before routing unfamiliar failures through it
Broader MCP, proxy, or application-level context compression	Headroom	More integration surfaces and an explicit hash-based retrieval path	The useful compression path was heavier to prepare, and some inputs were intentionally passed through
Failure triage where one omitted line changes the next action	Neither by default	Both first responses missed locked facts in the mixed failure fixture	Keep raw output available and count the recovery read
A layered deployment	Possibly both, with separate jobs	RTK can sit at the command layer while Headroom operates at a broader context layer	The combined stack was not tested, so this is an architecture option, not a measured winner

This is not a universal benchmark. It is a controlled comparison of five synthetic inputs under named versions and a shared success condition.

Test conditions

The controlled comparison used Headroom 0.34.0 and RTK 0.44.2 on an Apple arm64 Mac. RTK came from the official release archive, whose SHA-256 matched the release metadata and published checksums. Headroom came from PyPI in a disposable virtual environment.

The inputs were ToolFlock-owned:

• a 48-test successful log with a result line and next command;
• a mixed pass/fail log with one failing test, error code, source path, and next command;
• a 33-item JSON response whose decisive failure was the last item;
• git status --short from a disposable repository;
• a Git diff that included a deleted file, a changed source file, and a next-test comment.

Before either tool ran, the facts that had to survive were defined. UTF-8 bytes, lines, and a common cl100k_base token estimate were then measured. The token count is a reproducible payload estimate, not a model-provider bill.

Headroom was exercised through its standalone MCP compression method with proxy access disabled and an in-memory CCR store. Its official lightweight MCP dependency set installed successfully but passed these fixtures through. Adding the official proxy and ML dependencies still required the Kompress model to be warmed. After a synchronous warmup in an isolated model cache, the two verbose text logs compressed. That warmed profile is the Headroom result reported below.

RTK ran directly as rtk log, rtk json, rtk git, and rtk test. Its database, tee files, audit state, and telemetry setting were redirected into the disposable test root. Neither product's client-registration nor hook installer ran.

The first-response result

Fixture	Raw tokens	Headroom	Locked facts kept	RTK	Locked facts kept
Successful log	2,073	1,266 (-38.9%)	2/2	34 (-98.4%)	0/2
Mixed failure log	2,214	1,368 (-38.2%)	2/4	55 (-97.5%)	2/4
Structured JSON	2,016	2,016 (0%)	4/4	112 (-94.4%)	0/4
Git status	17	17 (0%)	3/3	16 (-5.9%)	3/3
Git diff	177	177 (0%)	3/3	166 (-6.2%)	3/3

RTK's generic log filter reduced the successful log to a five-line log summary. That summary reported zero errors, warnings, and info messages. It did not include the controlled test result or the next integration command, so it failed the success condition despite the 98.4% reduction.

On the mixed failure log, both products kept E_LEDGER_409 and src/payments/refunds.ts:214. Both omitted payments::refunds::test_replay_guard and the complete npm test -- refunds --runInBand command. Headroom's compressed marker made the retrieval route visible. RTK's direct log output did not emit a raw-output hint on that successful filter invocation.

The useful conclusion is narrow: for an unfamiliar log grammar, neither first response was sufficient to choose the exact next action without another read.

JSON showed the sharpest trade-off

The JSON fixture placed 32 healthy service records before one failed checkout-db record. The failed record contained E_DB_503, services/checkout/db.ts:91, and the next test command.

Headroom classified this as protected error output and returned it unchanged. It saved nothing, but it retained all four required facts. RTK produced a compact structural view with the first array item and a count for the remaining 32. That cut the estimate by 94.4%, but none of the four failure facts survived the first response.

This does not prove that RTK loses every nested failure. It proves that input order and filter semantics matter. A compact representation of structure is not automatically a useful representation of priority.

The Git result was less dramatic and more useful

Both tools kept every locked fact in the small Git status and diff inputs. Headroom passed the output through unchanged. RTK's Git path made modest reductions: 5.9% in the token estimate for status and 6.2% for the diff.

That is a better operational result than an impressive reduction paired with a missing action. The input was already compact, so there was little redundant material to remove. A system that knows when not to compress can be doing the right thing.

The diff path also demonstrates why product scope matters. RTK was operating through a Git-aware command. Headroom received the captured text through a generic MCP compression method. Those are officially supported paths to the same underlying evidence, but they are not identical internal mechanisms.

Recovery changes the effective cost

Headroom's strongest result was not its first-response reduction. Every original was stored in the isolated CCR cache and recovered byte-for-byte with one headroom_retrieve call. That includes the compressed logs and the inputs it had passed through.

RTK also has a recovery mechanism, but its tested boundary was different. The mixed-failure fixture ran through rtk test with a deliberate non-zero exit. RTK returned a filtered summary, named a tee file, and that file matched the raw 8,178-byte fixture exactly. One additional file read restored the evidence.

The distinction matters. Headroom makes retrieval part of its compression result. RTK's failure tee is tied to command execution and tee policy. The tee was verified on the failing test runner; no universal raw-output path was established for every successful rtk log or rtk json transformation.

Neither result establishes the final session saving. If the agent needs a second tool call, another file read, or a rerun before it can act, that recovery enters the context too. A payload reduction can still be valuable, but the first response is not the whole accounting unit.

Setup surface is part of the decision

RTK reached the tested commands as a 7.5 MB extracted release binary. Its hook was not installed. That kept the trust boundary visible: explicit commands in, filtered output out, isolated local state.

Headroom's official product surface is broader. It can run as a Python library, proxy, MCP server, or wrapper around supported clients. The broader surface also introduces more setup choices. The lightweight MCP-equivalent environment did not compress these fixtures. The warmed test profile, after proxy and ML dependencies, occupied 1.1 GB in the disposable virtual environment and used a 263 MB isolated model cache. Those are measurements of this Python 3.14 test profile—not universal install sizes—but they are large enough to affect first-use planning.

Headroom's official quickstart recommends richer install profiles for the full compression stack. RTK's official repository emphasizes a direct CLI proxy and optional agent hooks. Neither setup is inherently better. They create different operating and review surfaces.

Which should you use?

Use RTK first when your workload is dominated by well-understood developer commands and you are willing to validate the specific filter for each command family. Its aggressive reductions are most useful when the retained summary matches the decisions your agent actually makes.

Use Headroom first when you need a broader context layer, multiple integration surfaces, and a visible retrieval contract. Budget for the actual install profile, model warmup, cache behavior, and CCR lifetime you intend to operate. Do not assume that installing the lightweight MCP surface means every input will compress immediately.

Use neither as the only copy of unfamiliar failure output. Keep raw evidence available until you have tested the grammar that matters: failing unit, error code, source path, changed file, and next action.

Use both only after assigning separate responsibilities. RTK can filter known command output; Headroom can manage broader context and retrieval. The combined stack was not tested, so the safe next step is a shadow run on repeated real workflows—not a production-wide hook rollout.

The comparison started with a percentage question. The test ended with a better one: when the compact answer is incomplete, can the agent recognize that fact and recover the original before it makes the wrong move?