🤖 I have created a release *beep* *boop* --- ## [0.44.0](https://github.com/headroomlabs-ai/headroom/compare/v0.43.1...v0.44.0) (2026-11-09) ### ⚠ BREAKING CHANGES * **packaging:** keep PyTorch extras out of all ([#4067](https://github.com/headroomlabs-ai/headroom/issues/4067)) ### Features * **pipeline:** say whose request an OutcomeSnapshot is ([#4698](https://github.com/headroomlabs-ai/headroom/issues/4698)) ([a2bcbd1](https://github.com/headroomlabs-ai/headroom/commit/a2bcbd101b1391debfd218ec8c63cb72d2bc240a)) * **providers:** add Hermes agent wrap support ([#934](https://github.com/headroomlabs-ai/headroom/issues/934)) ([7877241](https://github.com/headroomlabs-ai/headroom/commit/7877241d84c93b3ec487e07324245838ddae85cc)) * **proxy/model-router:** add shadow mode (HEADROOM_MODEL_ROUTER_LOG_ONLY) ([#2395](https://github.com/headroomlabs-ai/headroom/issues/2395)) ([861ef95](https://github.com/headroomlabs-ai/headroom/commit/861ef95620c801c2560a2eacc5773a26e131dfd0)) * **proxy:** add lossless /v1/compress mode and detect provider by wire shape ([#4617](https://github.com/headroomlabs-ai/headroom/issues/4617)) ([33f067a](https://github.com/headroomlabs-ai/headroom/commit/33f067a243b2e648730c01ae6b9f20cba879f351)) * **proxy:** expose per-request cost_usd in /stats recent_requests ([#1079](https://github.com/headroomlabs-ai/headroom/issues/1079)) ([#1565](https://github.com/headroomlabs-ai/headroom/issues/1565)) ([84cedbf](https://github.com/headroomlabs-ai/headroom/commit/84cedbf2b4197f09ace9944c50655786dac35b03)) * **proxy:** expose shared Redis store availability in /health and /metrics ([#4578](https://github.com/headroomlabs-ai/headroom/issues/4578)) ([602ca65](https://github.com/headroomlabs-ai/headroom/commit/602ca65126e12d73ef44d4b1b01bbe1fa3b37080)) * **proxy:** give turn hooks one conversation id per client conversation ([#4496](https://github.com/headroomlabs-ai/headroom/issues/4496)) ([94a99ed](https://github.com/headroomlabs-ai/headroom/commit/94a99ed20f6fe110e03d2613e9feec42d9547150)) * **proxy:** report DeepSeek as its own provider in dashboard ([#2565](https://github.com/headroomlabs-ai/headroom/issues/2565)) ([9ad16a7](https://github.com/headroomlabs-ai/headroom/commit/9ad16a77f8b9a7817331aa5e9a9ee04d1e1fc05e)) * **proxy:** show per-request /stats metadata to token-authenticated callers ([#4168](https://github.com/headroomlabs-ai/headroom/issues/4168)) ([9b2dec5](https://github.com/headroomlabs-ai/headroom/commit/9b2dec56f9882a25fb511dc5f480b047845141f9)) * **proxy:** unified multi-upstream routing for Anthropic Cloud and local oMLX ([#4597](https://github.com/headroomlabs-ai/headroom/issues/4597)) ([f896161](https://github.com/headroomlabs-ai/headroom/commit/f896161340893dd8e96502d4c309980bed52d3d1)) * **savings:** carry cumulative actual output_tokens in history checkpoints ([#2921](https://github.com/headroomlabs-ai/headroom/issues/2921)) ([8388ff5](https://github.com/headroomlabs-ai/headroom/commit/8388ff5efd7caf3a827e66bf69449c4a64df05af)) * **wrap:** add `headroom wrap droid` for Factory Droid ([#4143](https://github.com/headroomlabs-ai/headroom/issues/4143)) ([bb8d18a](https://github.com/headroomlabs-ai/headroom/commit/bb8d18a56abb07ca7e811235c86ea6b626eb1f8b)) * **wrap:** make the Serena code-memory MCP opt-in ([#4509](https://github.com/headroomlabs-ai/headroom/issues/4509)) ([2649835](https://github.com/headroomlabs-ai/headroom/commit/2649835a51e6d459ac47e8dcb8591e5bf027715b)) ### Bug Fixes * **asgi:** stop buffering when the client disconnects (GHSA-mc2f-vg4v-2fh4) ([#4701](https://github.com/headroomlabs-ai/headroom/issues/4701)) ([c6d7081](https://github.com/headroomlabs-ai/headroom/commit/c6d708144ce27abeb08c4c57374b373eebe1951e)) * **beacon:** enforce the allowlist below the top-level keys ([#4691](https://github.com/headroomlabs-ai/headroom/issues/4691)) ([456288d](https://github.com/headroomlabs-ai/headroom/commit/456288da0765985ca31eed58dbdaef44ff9aa43a)) * **binaries:** fail closed on HEADROOM_BINARIES_ALLOW_UNVERIFIED=0/false ([#3218](https://github.com/headroomlabs-ai/headroom/issues/3218)) ([da6d973](https://github.com/headroomlabs-ai/headroom/commit/da6d9736cd82074988c7d0a2360b49d9d8b6c0a0)) * **cache:** record TTL observations with relative filenames ([#4711](https://github.com/headroomlabs-ai/headroom/issues/4711)) ([51d9dc5](https://github.com/headroomlabs-ai/headroom/commit/51d9dc59b3dc6b8c386cc2293e78d1334aac0893)) * **cache:** round learned TTL upper bounds up to whole seconds ([#4710](https://github.com/headroomlabs-ai/headroom/issues/4710)) ([13347e3](https://github.com/headroomlabs-ai/headroom/commit/13347e339c4cc88dfa0cfa1deceeb0dae56ee2fc)) * **cache:** save prefix-tracker state when the exit signal arrives ([#4715](https://github.com/headroomlabs-ai/headroom/issues/4715)) ([3ba4223](https://github.com/headroomlabs-ai/headroom/commit/3ba422361e3bce92afd6bb30e3cd817ec3b9cb46)) * **ccr:** lowercase the hash in the streaming feedback recorders ([#2313](https://github.com/headroomlabs-ai/headroom/issues/2313)) ([3912c04](https://github.com/headroomlabs-ai/headroom/commit/3912c0405321c498f854fd0c152ae01abf63bf48)) * **ci:** keep the npm publish token out of install and build steps ([#4690](https://github.com/headroomlabs-ai/headroom/issues/4690)) ([8f6366c](https://github.com/headroomlabs-ai/headroom/commit/8f6366cf66d035fc8e9f390be424bc9bdf6c62e4)) * **cli:** resolve active proxy port for read commands ([#3522](https://github.com/headroomlabs-ai/headroom/issues/3522)) ([02c4e92](https://github.com/headroomlabs-ai/headroom/commit/02c4e922f748cfac5db59303918bb13906031650)) * **content-router:** trust confident HTML detection over mixed-content heuristics ([#3627](https://github.com/headroomlabs-ai/headroom/issues/3627)) ([f50db67](https://github.com/headroomlabs-ai/headroom/commit/f50db67006e2fe3f43b295542b759d90bb73e5a1)) * **dashboard:** lifetime metrics and refresh ([#2374](https://github.com/headroomlabs-ai/headroom/issues/2374)) ([eb9932a](https://github.com/headroomlabs-ai/headroom/commit/eb9932a671c92b19c58949a63ec833869fc1a8e7)) * **doctor:** recognize IPv6 loopback and case-insensitive proxy routing URLs ([#3255](https://github.com/headroomlabs-ai/headroom/issues/3255)) ([2b0315b](https://github.com/headroomlabs-ai/headroom/commit/2b0315b2d4b0d54947050bbdad2de9e89df06378)) * **install:** decode Windows Task Scheduler XML output before parsing ([#3969](https://github.com/headroomlabs-ai/headroom/issues/3969)) ([#4064](https://github.com/headroomlabs-ai/headroom/issues/4064)) ([b78e07d](https://github.com/headroomlabs-ai/headroom/commit/b78e07da7fadeaafdbba16312140d44f812bc181)) * **install:** make install status agree with doctor when the proxy is reachable ([#3072](https://github.com/headroomlabs-ai/headroom/issues/3072)) ([#3141](https://github.com/headroomlabs-ai/headroom/issues/3141)) ([05431b2](https://github.com/headroomlabs-ai/headroom/commit/05431b264f4fc105a302cceed60b5327abc35e10)) * **langchain:** check optional integration availability ([#4042](https://github.com/headroomlabs-ai/headroom/issues/4042)) ([cde584d](https://github.com/headroomlabs-ai/headroom/commit/cde584d7fe6930b8ecf612b705e984b2c6a41527)) * **learn:** harden analyzer JSON parsing against malformed LLM output ([#2471](https://github.com/headroomlabs-ai/headroom/issues/2471)) ([12864fc](https://github.com/headroomlabs-ai/headroom/commit/12864fc8f01a1ca6c58440eccef0dabdd3e595b8)) * **learn:** support opencode v2 session schema in learn scanner ([#4199](https://github.com/headroomlabs-ai/headroom/issues/4199)) ([c05466a](https://github.com/headroomlabs-ai/headroom/commit/c05466a469c848c69a62a5c283c09dcd35d8e9c8)) * **lossless:** fold only pure path listings, never markup ([#4716](https://github.com/headroomlabs-ai/headroom/issues/4716)) ([0ccd559](https://github.com/headroomlabs-ai/headroom/commit/0ccd559db052ea2ec8baef122ac769a146a75518)) * **memory:** gracefully degrade on context lookup and initialization errors ([#3251](https://github.com/headroomlabs-ai/headroom/issues/3251)) ([#4049](https://github.com/headroomlabs-ai/headroom/issues/4049)) ([00d4f44](https://github.com/headroomlabs-ai/headroom/commit/00d4f441d3f1d48c463fea57e6c574c2f3671302)) * **metrics:** cap savings_by_source rows and fold the rest into other ([#4257](https://github.com/headroomlabs-ai/headroom/issues/4257)) ([2038fb2](https://github.com/headroomlabs-ai/headroom/commit/2038fb2a3667d9cba3ff9cb1c4957add06ef5acb)) * **packaging:** keep PyTorch extras out of all ([#4067](https://github.com/headroomlabs-ai/headroom/issues/4067)) ([a890521](https://github.com/headroomlabs-ai/headroom/commit/a8905214d949cdc42b1d76fbc83146f51e0c4f19)) * **proxy:** add --no-ccr-response-handling flag to bypass response buffering ([#3082](https://github.com/headroomlabs-ai/headroom/issues/3082)) ([#3100](https://github.com/headroomlabs-ai/headroom/issues/3100)) ([ce14271](https://github.com/headroomlabs-ai/headroom/commit/ce14271ba8ca66b653fbbb555d50ca20e7a36d3f)) * **proxy:** bound the Bedrock Prometheus model label ([#4694](https://github.com/headroomlabs-ai/headroom/issues/4694)) ([d70a8b7](https://github.com/headroomlabs-ai/headroom/commit/d70a8b76a5bc12b4eae6655e40e60abe19b145d0)) * **proxy:** drop headers named by Connection when forwarding responses ([#4674](https://github.com/headroomlabs-ai/headroom/issues/4674)) ([3871b36](https://github.com/headroomlabs-ai/headroom/commit/3871b3664a03c9dc489be13f245462f2a9fc0b67)) * **proxy:** keep cold-turn reasoning drops sticky so the next warm turn reuses the cached prefix ([#4592](https://github.com/headroomlabs-ai/headroom/issues/4592)) ([3544cf5](https://github.com/headroomlabs-ai/headroom/commit/3544cf5b88a0d0e704f3d3c5eb8a89f7c52d8c13)) * **proxy:** keep the Bedrock credentials provider when startup resolution fails ([#4705](https://github.com/headroomlabs-ai/headroom/issues/4705)) ([5438f00](https://github.com/headroomlabs-ai/headroom/commit/5438f0035d2fd0261b50aac0520b30021dc56fe0)) * **proxy:** refresh Bedrock AWS credentials before they expire ([#4696](https://github.com/headroomlabs-ai/headroom/issues/4696)) ([adc6724](https://github.com/headroomlabs-ai/headroom/commit/adc67249660b4464e8489e21287d9b95d044b095)) * **proxy:** rename leaked_threads metric to timed_out_workers_total ([#3908](https://github.com/headroomlabs-ai/headroom/issues/3908)) ([bd164a2](https://github.com/headroomlabs-ai/headroom/commit/bd164a2c3ba3a2eeb470a0b9503a696dd02b0e9c)) * **proxy:** track response.-prefixed item and content-part events in Responses SSE state ([#4695](https://github.com/headroomlabs-ai/headroom/issues/4695)) ([8f4122f](https://github.com/headroomlabs-ai/headroom/commit/8f4122f4e5ae351703c775e042d2ad705cebc143)) * **router:** compress tool_result blocks in mutable window with trailing messages ([#4717](https://github.com/headroomlabs-ai/headroom/issues/4717)) ([0511bcd](https://github.com/headroomlabs-ai/headroom/commit/0511bcd33186f57d76e508bbec388bb4256cfc68)) * **router:** ignore shell operators inside quoted arguments in read detection ([#4646](https://github.com/headroomlabs-ai/headroom/issues/4646)) ([8cdce17](https://github.com/headroomlabs-ai/headroom/commit/8cdce172ea5b70f9ed5300f089c11f4ca23b8c66)) * **scripts:** skip ci-precheck in the pre-push hook when a push only deletes refs ([#4702](https://github.com/headroomlabs-ai/headroom/issues/4702)) ([cbcf8d8](https://github.com/headroomlabs-ai/headroom/commit/cbcf8d8d9b3c43a93276b46db569fab185ed949d)) * **sdk:** keep Vercel AI SDK tool-result output kinds through compression ([#4670](https://github.com/headroomlabs-ai/headroom/issues/4670)) ([ce42754](https://github.com/headroomlabs-ai/headroom/commit/ce4275491299231bc9d2907833f72f72ea22b8a9)) * **search_compressor:** keep kept rows byte-for-byte and in input order ([#3982](https://github.com/headroomlabs-ai/headroom/issues/3982)) ([a538740](https://github.com/headroomlabs-ai/headroom/commit/a538740ee40a80642bb1092d179171828260696c)) * **smart-crusher:** keep mixed-array dict rows and exact drop count with factor_out_constants ([#4692](https://github.com/headroomlabs-ai/headroom/issues/4692)) ([ced2685](https://github.com/headroomlabs-ai/headroom/commit/ced26852c6d103991e05c5eec1f13103e5ce2755)) * **smart-crusher:** keep the row the question names ([#4713](https://github.com/headroomlabs-ai/headroom/issues/4713)) ([e6e2ebb](https://github.com/headroomlabs-ai/headroom/commit/e6e2ebb6782119e46400a66cef33bb8eb9295484)) * **storage:** return the latest snapshot from JSONLStorage.get ([#4675](https://github.com/headroomlabs-ai/headroom/issues/4675)) ([b25c45b](https://github.com/headroomlabs-ai/headroom/commit/b25c45b08f1cc5ed8fe49671e356711b89800ac1)) * **tabular:** split fixed-width rows on column boundaries, not on double spaces ([#4541](https://github.com/headroomlabs-ai/headroom/issues/4541)) ([b80245e](https://github.com/headroomlabs-ai/headroom/commit/b80245ea73e452f2c14de7a5cd8520f7e7d92c61)) * **tag-protector:** do not treat a slash in an unquoted attribute as self-closing ([#4681](https://github.com/headroomlabs-ai/headroom/issues/4681)) ([d5644cb](https://github.com/headroomlabs-ai/headroom/commit/d5644cbacab79607fe8864d007810aa06c5c68ea)) * **tag-protector:** keep the enclosing tag open after a nested close in marker mode ([#4682](https://github.com/headroomlabs-ai/headroom/issues/4682)) ([385d487](https://github.com/headroomlabs-ai/headroom/commit/385d487f41abd029fb4e2f8346c0cc30dc546bc4)) * **telemetry:** keep install ID stateless ([#3542](https://github.com/headroomlabs-ai/headroom/issues/3542)) ([27bba79](https://github.com/headroomlabs-ai/headroom/commit/27bba79ff2d1800e390ed20820adff971e99ce08)) * **tokenizers:** resolve chatgpt-4o-* aliases to o200k_base ([#4672](https://github.com/headroomlabs-ai/headroom/issues/4672)) ([9648d2d](https://github.com/headroomlabs-ai/headroom/commit/9648d2d867c99eb7e91f81754c5e2877be56feac)) * **tokenizers:** unwrap BatchEncoding in HuggingFaceTokenizer.count_messages ([#2447](https://github.com/headroomlabs-ai/headroom/issues/2447)) ([9eed58f](https://github.com/headroomlabs-ai/headroom/commit/9eed58f84cacc30116c6b6b29cb99eade57e0edf)) * **vertex:** explain Vertex failures in-band, correct the model/region matrix ([#2640](https://github.com/headroomlabs-ai/headroom/issues/2640)) ([0ddaa56](https://github.com/headroomlabs-ai/headroom/commit/0ddaa56c21cdc01c4774391fdcc69e987ecc4e5c)) * **wrap:** route Claude Code's Bedrock mode through Headroom ([#4316](https://github.com/headroomlabs-ai/headroom/issues/4316)) ([aa2093b](https://github.com/headroomlabs-ai/headroom/commit/aa2093b4a08ca1f1bb9c8fb92fe0fc85d9ffe936)) ### Dependencies * bump rusqlite from 0.40.2 to 0.41.1 ([#4658](https://github.com/headroomlabs-ai/headroom/issues/4658)) ([74b7ac2](https://github.com/headroomlabs-ai/headroom/commit/74b7ac23861944f1411d30c5394043ec0505b334)) * bump the cargo-minor-patch group with 3 updates ([#4657](https://github.com/headroomlabs-ai/headroom/issues/4657)) ([c01cf07](https://github.com/headroomlabs-ai/headroom/commit/c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4)) * bump the npm-minor-patch group across 1 directory with 2 updates ([#4650](https://github.com/headroomlabs-ai/headroom/issues/4650)) ([def4ef1](https://github.com/headroomlabs-ai/headroom/commit/def4ef10099514d09188326852138a8b20c26237)) * update click requirement from >=8.3.3 to >=8.5.0 ([#4655](https://github.com/headroomlabs-ai/headroom/issues/4655)) ([ea59ac3](https://github.com/headroomlabs-ai/headroom/commit/ea59ac3eef3a3dc02076e9fe4bb30d572ca9c1a9)) * update sqlite-vec requirement from >=0.1.6 to >=0.1.9 ([#4654](https://github.com/headroomlabs-ai/headroom/issues/4654)) ([de1a1e0](https://github.com/headroomlabs-ai/headroom/commit/de1a1e0f478d1eb9257dd8dd0d4ac87c9e6fc639)) * update tree-sitter requirement from <0.27,>=0.25.2 to >=0.26.0,<0.27 ([#4656](https://github.com/headroomlabs-ai/headroom/issues/4656)) ([910588e](https://github.com/headroomlabs-ai/headroom/commit/910588e6b15ab54c4099d03703e5fa20c8abb757)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: headroom-release[bot] <352661243+headroom-release[bot]@users.noreply.github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
headroom-snip
A Claude Code mod that shows what Headroom does to each request, live. When a request goes through the proxy, a pair of scissors runs along a bar the size of the original prompt, cuts it down to what was actually sent, and the token count drops as it goes:
✂ headroom 21k → 16k tok ━━━━━━━━━━━━━━━━━━━━━━━✂⡀⠄⠂⠁⢀⠈⠐⠠ −81%
✂ headroom 21k → 7.6k tok ━━━━━━━━━━━✂⠈⠐⠠⡀⠄⠂⠁⢀⠈⠐⠠⡀⠄⠂······ −81%
✂ headroom 21k → 4.1k tok ━━━━━━·························· −81%
JSON crush ×2 · Kompress text · cache align project 184k saved (62%) over 23 req ≈ 307 pages details hide
What it shows
- The band above the prompt. The latest request: original → sent tokens,
the snip animation, and the percentage cut. Below that, which compressors did
the cutting (
JSON crush,code AST,Kompress text,log squash,cache align, ...) and the running total since the session started. A request sent unchanged says why, for examplekept: user message, recent codeornothing worth a snip. /headroom. Opens a pane with the requests since the session started: one bar per request, what was cut and what was protected, how long compression took, the biggest snip so far, and an all-time total./headroom hideand/headroom showtoggle the band.- The status line.
✂ 184k tok saved · 62%. - Milestone toasts at 10k, 50k, 100k, 250k, 500k, 1M and 5M tokens saved.
- No proxy? If nothing answers, the band says so and suggests
headroom wrap claude.
How it works
While a turn runs, the mod polls the proxy's loopback GET /stats?cached=1
once a second. It reads the recent_requests tail (per-request token counts
and transforms_applied), and keeps polling for a few seconds after the turn
ends. Requests stamped before the session started count as history: they
aren't animated or added to the totals, even if the proxy only comes up later.
Nothing leaves your machine.
The proxy can't tell Claude Code sessions apart, so the totals are never per session. What they cover depends on how Claude Code reaches the proxy:
- Through
headroom wrap claude: each request carries anX-Headroom-Projectheader naming the launch directory (its basename, so two directories with the same name share a tag). The mod counts every request with this session's tag, including other sessions in the same project, and leaves other projects out. The proxy only reports tags for its last ten requests, so a request it can't attribute is left out rather than guessed. The band says "project" and/headroomnames the project. - Any other way: there is no tag, so the totals cover every client on the
proxy since this session started. The band says "proxy" and
/headroomsays so.
It finds the proxy in this order:
HEADROOM_PROXY_URLANTHROPIC_BASE_URL(asheadroom wrap claudesets it)http://127.0.0.1:8787
Only loopback URLs are used: http or https on exactly localhost, 127.0.0.1
or [::1], with no user or password. A value that isn't one (a remote proxy, or a
host like localhost.example.com) is skipped, so the mod never polls a remote host.
Install
claude plugin marketplace add headroomlabs-ai/headroom
claude plugin install headroom-snip@headroom-marketplace
Or, from a checkout: claude --plugin-dir plugins/headroom-snip.
Develop
claude plugin validate plugins/headroom-snip
claude plugin test plugins/headroom-snip # tests/snip.test.tsx
tsc -p plugins/headroom-snip # after Claude Code has loaded it once
hooks/snip.ts holds the pure parts (parsing, transform labels, the animation
frames) and hooks/register.tsx holds the hooks and drawing.