token-optimization on tomrochette.com

Headroom

tom@tomrochette.com (Tom Rochette) — Wed, 07 Oct 2026 00:00:00 +0000

Headroom is the Apache-2.0 context compression layer that rewrites everything an agent reads, tool outputs, logs, files, RAG chunks, and conversation history, before it reaches the LLM, keeping the signal and discarding the repetition, with the full originals retrievable on demand.

Headroom is the generalization of rtk’s idea into a product surface: where rtk filters one channel, command output, Headroom compresses every input channel, ships as a library, proxy, agent wrapper, and MCP server at once, and makes the loss reversible through a retrieve tool the model can call back.

What it is
#

A Python and TypeScript library, a zero-code-change proxy (headroom proxy --port 8787), a one-command wrapper around fourteen coding agents (headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|zcode), and an MCP server, from headroomlabs-ai (74,551 stars, pushed 2026-10-07, as of 2026-10-07). Compression runs locally: statistical analysis keeps errors, anomalies, and boundaries in JSON arrays, a ModernBERT token classifier squeezes plain text, AST-aware compression (opt-in) collapses function bodies to signatures, an ML router resizes images, and everything removed lands in a Compress-Cache-Retrieve store the model can query through headroom_retrieve. A shared cross-agent memory store deduplicates content across Claude, Codex, Gemini, and Grok sessions, and a headroom learn command tunes the compressor. The docs’ reproducible benchmarks (seeded, generated from MCP output formats, gpt-5.6 tokenizer) show 57 percent savings on an SRE incident dump (55,957 to 24,340 tokens), 42 percent on codebase exploration, and 21 percent on code search, with an explicit warning that savings depend on how repetitive your content is.

Status
#

Active and compounding fast: created 2026-01-07, 74,551 stars and 5,770 forks in nine months, PyPI package at 0.40.0, about 39,200 npm downloads in the week to 2026-10-04, as of 2026-10-07.

Trendshift ranked it the number-one repository of the day during its surge. The HN footprint is modest for the star count (three submissions, the largest at 10 points in July 2026), a gap worth noticing either as marketing-driven adoption or as a signal that star velocity outran practitioner debate.

Strengths
#

One mechanism (compress, then retrieve on demand) covers every input channel, where channel-specific filters leave logs, RAG, and history uncompressed.
The retrieve path changes the risk calculus of aggressive compression, since the model can pull back any discarded original instead of hallucinating it.
Local-only compression with a stated no-content-sent policy keeps the layer palatable for private repos.
Deployment breadth: the same compressor reaches apps (library), existing agents (wrap), arbitrary HTTP clients (proxy), and MCP clients without code changes.

Cautions
#

The benchmark corpus is generated and seeded rather than production telemetry, and the docs say so; treat the percentages as reproducible upper references, not guarantees for your workload.
AST-aware code compression is opt-in and off by default, so the default code path is less aggressive than the headline suggests.
415 open issues against nine months of explosive growth signals support strain.
A compression layer in the hot path is one more thing that can be wrong subtly, and the correctness of what survives compression is exactly as good as the statistical heuristics.

Pricing
#

Free and open source under Apache-2.0; there is no paid tier, so pricing does not apply. Costs are your own hardware for the compression pass.

Compared to
#

rtk: the category’s established output filter, Rust, per-command; Headroom is the broader, multi-channel sibling with a retrieve path, rtk the leaner proxy with a longer track record in this section.
Repomix: the packer that solves token cost by shrinking what you send once; Headroom solves it by shrinking everything the agent reads continuously.
Semble: attacks the same bill by retrieving less from an index; Headroom compresses whatever the agent retrieves anyway.

Bottom line
#

Recommended for teams with measurable token spend dominated by tool output, logs, and RAG noise, starting with the proxy on one noisy workflow and auditing what survives compression before trusting it broadly. Not as a substitute for retrieval quality (compressing bad context makes bad context cheaper), and not where an unaudited transformation in the agent loop is unacceptable.

Changes
#

2026-10-07 - Created.

References
#

https://github.com/headroomlabs-ai/headroom - repository, Apache-2.0 license, deployment surfaces, the agent wrap list, and the CCR store (fetched 200, 2026-10-07)
https://api.github.com/repos/headroomlabs-ai/headroom - stars, forks, open issues, created date, and push date for the as-of status (fetched 200, 2026-10-07)
https://docs.headroomlabs.ai/docs - the compression table by content type, the seeded benchmark table with its own caveats, and the framework integrations (fetched 200, 2026-10-07)
https://pypi.org/pypi/headroom-ai/json - the published package version 0.40.0 (fetched 200, 2026-10-07)
https://api.npmjs.org/downloads/point/last-week/headroom-ai - weekly npm download volume for the adoption claim (fetched 200, 2026-10-07)
https://hn.algolia.com/api/v1/items/48999841 - the largest Headroom thread, 10 points, July 2026, grounding the modest-HN-footprint observation (fetched 200, 2026-10-07)

TOON

tom@tomrochette.com (Tom Rochette) — Wed, 07 Oct 2026 00:00:00 +0000

TOON (Token-Oriented Object Notation) is an MIT-licensed, spec-backed encoding of the JSON data model that replaces braces and repeated keys with indentation and CSV-style table rows, cutting the token cost of structured data handed to LLMs while staying lossless and human-readable.

TOON is the packing convention for the structured slice of the context window: it changes nothing about which data enters the window, only how many tokens the same data costs, and its 1.9 million weekly npm downloads make it the most-adopted encoding standard this category holds.

What it is
#

A format specification (version 4.3, Working Draft, 2026-10-06) maintained in its own repository by Johann Schopplich, with the TypeScript reference implementation at @toon-format/toon and community ports across languages (25,461 stars, pushed 2026-10-06, as of 2026-10-07). The design combines YAML’s indentation for nested objects with CSV-style tabular rows for arrays of uniform objects: each array declares its length and field list once, then one row per item, with a single active delimiter (comma, tab, or pipe) and strings quoted only when required. The sweet spot is uniform data, the same fields across many items, where it approaches CSV compactness while keeping structure explicit; the spec itself concedes that deeply nested or non-uniform data can be cheaper as plain JSON. The intended use is a translation layer: keep JSON in code, encode to TOON at the prompt boundary, decode back from the model’s output.

Status
#

Active and widely adopted: created 2025-10-22, 25,461 stars, spec at v4.3, about 1,897,900 npm downloads in the week of 2026-09-28 to 2026-10-04, as of 2026-10-07.

The launch discussion reached 178 points and 58 comments on Hacker News in October 2025, where the standing objections were set: YAML already exists, and models fine-tuned on JSON might lose accuracy on a format absent from their training data. A third-party test comparing TOON against JSON and CSV on tabular data came out of that thread, and the spec continues to revise (4.1 to 4.3 across 2026), so the format is stable-but-moving by its own description.

Strengths
#

The token savings on uniform arrays are mechanical and measurable, and the format stays lossless, so it drops into an existing JSON pipeline as a prompt-boundary codec.
Explicit array lengths and per-row field elision make structure easy for models to validate, which is the argument against just using CSV.
A specification with conformance requirements and multiple independent implementations, not a single library’s output format.
Adoption at the 1.9-million-downloads-a-week level means tooling and precedent exist when something goes wrong.

Cautions
#

Accuracy effects are unresolved: TOON is not in most models’ training distributions, and the strongest community objection since launch is that JSON-heavy fine-tuning may make models measurably worse at reading it on long contexts.
The win inverts on nested or non-uniform data, so blind encoding can cost tokens rather than save them.
A young spec (first release late 2025, three revisions in 2026) that carries churn risk for anything storing TOON long-term.
Round-tripping adds a decode step and a failure mode at exactly the boundary where you are trying to save money.

Pricing
#

Free and open standard under MIT; there is no paid tier, so pricing does not apply.

Compared to
#

rtk: the compressor for unstructured tool output; TOON is the compressor for structured data you serialize yourself, and the two do not overlap.
Repomix: packs a whole repository into one file; TOON packs one JSON document into fewer tokens, and both are offline and deterministic.
MCP: the transport that moves the data; TOON is independent of how the data arrives and can encode an MCP tool’s payload at the prompt boundary.

Bottom line
#

Recommended for any pipeline that embeds large uniform JSON (tables, lists, logs of records) into prompts, measuring tokens before and after on your own model and data, since the format’s own docs treat the benchmark case as narrow. Not for deeply nested or heterogeneous payloads, and not yet for contexts where an unproven accuracy effect on your model is unacceptable.

Changes
#

2026-10-07 - Created.

References
#

https://github.com/toon-format/toon - repository, MIT license, README design rationale, and the benchmark framing (fetched 200, 2026-10-07)
https://api.github.com/repos/toon-format/toon - stars, created date, and push date for the as-of status (fetched 200, 2026-10-07)
https://raw.githubusercontent.com/toon-format/spec/HEAD/SPEC.md - the v4.3 specification: syntax, canonical number formatting, delimiter scoping, strict-mode validation, and conformance requirements (fetched 200, 2026-10-07)
https://api.npmjs.org/downloads/point/last-week/@toon-format/toon - weekly download volume for the adoption claim (fetched 200, 2026-10-07)
https://hn.algolia.com/api/v1/items/45715632 - the 178-point launch thread with the YAML and training-data-accuracy objections (fetched 200, 2026-10-07)

token-optimization on tomrochette.com

Headroom

What it is
#

Status
#

Strengths
#

Cautions
#

Pricing
#

Compared to
#

Bottom line
#

Changes
#

See also
#

References
#

TOON

What it is
#

Status
#

Strengths
#

Cautions
#

Pricing
#

Compared to
#

Bottom line
#

Changes
#

See also
#

References
#

token-optimization on tomrochette.com

Headroom

What it is #

Status #

Strengths #

Cautions #

Pricing #

Compared to #

Bottom line #

Changes #

See also #

References #

TOON

What it is #

Status #

Strengths #

Cautions #

Pricing #

Compared to #

Bottom line #

Changes #

See also #

References #

What it is
#

Status
#

Strengths
#

Cautions
#

Pricing
#

Compared to
#

Bottom line
#

Changes
#

See also
#

References
#

What it is
#

Status
#

Strengths
#

Cautions
#

Pricing
#

Compared to
#

Bottom line
#

Changes
#

See also
#

References
#