RTK: what the numbers actually say

01 · the headline

The savings are real, and they are not evenly spread

rtk gain reports 64.6M tokens saved across 47,075 proxied commands, a 31.2% average reduction on 206.9M input tokens. That number is true. It is also an average over wildly different commands, and the average is the least useful way to read it.

One row carries the whole story: 568 test runs saved 28.6M tokens, which is 44% of everything RTK has ever saved here. A test runner's summary genuinely is the useful output, so compressing the other 15% of its log costs nothing.

02 · concentration

1.3% of commands produce 46% of the savings

Split the 64.6M by what kind of command earned it. Test and lint runners (vitest, pytest, eslint) are 623 commands, 1.3% of the total, and they account for 29.6M. Search and read (grep, read, find) are 9,448 commands, 20% of the total, for 23.3M.

This matters because the two halves carry different risk. The runner half has no retry risk: nobody needs line 400 of a passing vitest log. The search half is where the complaint lives.

03 · the complaint

The failure they describe is real, and it has an exact shape

I ran 20 (pattern, file) pairs through plain grep and rtk grep on real repository files, from inside a script file, which the hook cannot rewrite, so grep was genuinely plain. The divergence is deterministic: rtk grep prints at most 25 matches. Thirteen pairs matched exactly, every one of them at or under 25. Seven diverged, every one of them over 25. Zero divergences below the ceiling.

04 · deep dive · עברית

מה בדיוק הם טוענים, שורה אחר שורה

219 matches in 1 files:

3:TypeScript hook system for the OrchestKit Claude Plugin...
...
66:│   │   ├── mcp/            # MCP integration hooks
  +194 more in src/hooks/README.md [see remaining: tail -n +26 "$HOME/.../1787985624_grep_0_s_da1929.log"]

מה שהמדד רואה                 מה שקרה באמת
─────────────────────         ──────────────────────────────
rtk grep   -97.9%  WIN        rtk grep    2,004 tok   קוצץ
                              rtk tail      ~900 tok   שליפה
                              ─────────────────────────
נרשם: ניצחון אחד              בפועל: שתי קריאות, שני תורות

05 · the part the thread missed

RTK does not hide the truncation. It announces it twice.

The capped output opens with the true total and closes with the shortfall plus the exact recovery command:

$ rtk grep -n "hook" src/hooks/README.md
219 matches in 1 files:

3:TypeScript hook system for the OrchestKit Claude Plugin...
...
66:│   │   ├── mcp/            # MCP integration hooks
  +194 more in src/hooks/README.md [see remaining: tail -n +26 "$HOME/.../1787985624_grep_0_s_da1929.log"]

That call went from 93,281 bytes to 2,004 bytes, a 97.9% reduction, while stating up front that 219 matches exist and 194 are one tail away. So this is not a silent lie. It is a disclosed trade with a documented escape hatch, and it only breaks when the agent skips the header or prefers to reformulate over running the tail.

Two corrections to my own prior notes while I am here. First, the case recorded on 2026-08-24, where grep supposedly could not find a string at line 991 of cc-triage.mjs, does not reproduce on 0.46.0: all six matches come back. Second, I earlier called the ceiling 26. It is 25. I had been counting RTK's own N matches in 1 files: header line as a match.

06 · the knob that does not turn

The documented fix for the ceiling is inert

There are two documented ways to raise the ceiling and a third documented way to compress harder. All three are inert. If any of them worked, the ceiling would be a configuration question and "you configured it wrong" would have a leg to stand on.

1. The CLI flag. rtk grep --help advertises -m, --max <MAX> Max results to show [default: 200].

2. The config key. RTK's own config --create template, and the upstream docs, both ship a [limits] block whose grep_max_per_file = 25 is exactly the ceiling I measured. Tested against the real config file, with a backup, in both directions:

The 5 row is the decisive one: a value below the ceiling should have shrunk the output, and did not. The positive control matters here, because a config that is never read looks identical to a key that is ignored. Setting [tee] enabled = false in the same file visibly changed the output, dropping the [see remaining: tail ...] hint from the footer. So the file is read and this key is ignored.

3. The compression flag. --ultra-compact, documented as a global "Level 2 optimizations" flag:

Same class of defect already found in rtk rewrite, whose --help promises exit 0 or 1 and which actually exits 3 with the rewrite on stdout. Documented contract, different behaviour.

What does work is [hooks] exclude_commands, and it is precise. After adding "grep -q", grep -q stopped being rewritten while grep -n kept its 16.8M. The list to add comes from rtk gain --failures, which logs 7,688 parse failures at a 100% recovery rate: grep -q 673 times (a predicate, where the exit code is the answer), uv sync 96, git stash 13, docker ps --format 8. Those are commands paying the RTK detour for nothing.

07 · adjudication

Scoring the thread

08 · the time series

The 31.2% average is the least honest number on this page

rtk gain --all breaks the lifetime figure into 88 days. Daily reduction ranges from 0.2% to 99.7%. There is no typical day. Averaging across that distribution produces a number that describes none of it, and it is the number the thread is arguing about.

July is the interesting month: the highest volume by far, and the worst rate. Three days explain almost all of it.

Read those two blocks together. Three days carried 51% of every token RTK has ever seen and produced 4% of the savings. Three other days produced 47% of all savings. This is not a tool with a 31% discount rate. It is a tool that is nearly free money on some workloads and pure overhead on others, and the lifetime average hides which one you are having.

That reframes the whole argument. Amit and Ron are not necessarily wrong about their own machines: they may simply be living in the low-compression mode, where RTK filters output that was never bulky to begin with and the truncation cost is not offset. My 31.2% is not evidence against their experience, because my own 31.2% is itself a blend of 99.7% days and 0.2% days.

09 · the money

65 million tokens is 0.5% of the bill

RTK ships a third view nobody in the thread ran. rtk cc-economics joins its own savings against ccusage's spend figure, and it is the only view that converts tokens into money. It is also the one that settles the argument.

Spent (ccusage):              $78,041.36
  Input:                      194.5M
  Output:                     203.0M
  Cache writes:             3,114.6M
  Cache reads:             75,164.4M      <-- RTK cannot touch any of this

RTK commands:                 47,122
Tokens saved:                 65.1M
Estimated savings:           $402.56  (0.5%)

Cache reads are 75.2 billion tokens against 194.5M of fresh input. RTK only ever sees command output entering context, which is a rounding error next to where the spend actually lives. So the savings are real, they are just 0.5% of the bill, and no amount of tuning the grep ceiling changes that ratio.

Which makes RTK's three headline numbers worth ranking, because they disagree with each other by two orders of magnitude:

One caveat kept honest: ccusage prices tokens at API list rates, so $78,041 is list-price-equivalent value rather than cash paid on a subscription. The 0.5% ratio survives that, because both sides of it are priced the same way.

10 · and on this machine

The hook was never dead. I was measuring it wrong.

Two earlier versions of this section claimed the hook was not firing and diagnosed why. Both diagnoses were wrong, and so was the claim. The transcript settles it: Claude Code records every hook run as an attachment on the tool call, with the hook's stdout, and RTK's stdout carries the literal string RTK auto-rewrite. That is a per-call record, not an inference.

The two commands I offered as proof of a dead hook were both misread, in different ways:

Across the whole estate, 7 days, 582 top-level transcripts:

bash calls        16,493
rewritable         2,174   (13.2%)
rewritten          2,101   hit rate on rewritable  96.6%

of the 156 rewritable calls without a rewrite:
  148  never executed at all (no PreToolUse attachments: interrupted or cancelled)
    4  a hook errored
    3  hooks ran, rtk produced nothing (multi-line commands, 22 Aug)
   -> on calls that actually ran, about 99.7%

So the honest adoption number is not a hook problem. Only 13% of Bash calls on this machine are shapes RTK can rewrite at all. That is the real finding, and it has a cause.

Nearly half of all commands are heredoc script files, and rtk rewrite cannot see inside a heredoc. That shape is not an accident. This machine carries a global rule that says write long, piped, or multi-stage commands to a script file and run that, and a display-lint hook that nudges the same thing on every prompt, for a real reason: terminal line-wrap splits flags from arguments. The rule is doing its job. It is also, silently, the single largest reason RTK touches 13% of commands instead of 50%. Two of my own safeguards were fighting each other, and neither could see the other.

That is a trade-off to decide with the numbers in view, not a bug to fix. It was invisible before because every instrument I reached for first, the buffered counter, the output shape, rtk discover, was answering a different question than the one I asked.

For the record, the two wrong diagnoses and what refuted each: (1) the bare rtk hook claude registration introduced on 22 Aug (commit 5309ba0) broke it: refuted by daily volume, 261 commands/day before vs 241 after with the peak day (928) under the bare form; (2) platform's 27 project-level PreToolUse groups shadow the global hook: refuted by rtk gain --project, platform has the highest adoption on the machine at 17,540 commands and 59.4%. And the instrument that would have prevented all of it, rtk discover, reports 0.0% adoption by construction: transcripts store the model's original command, never the rewritten one, so it cannot see a hook rewrite even when one happened on every call.

One more, found after the restart. I had repointed the registration at a wrapper script and called it harmless hardening. It was not harmless: the wrapper delegated to rtk rewrite, and rtk rewrite ignores RTK_HOOK_AUDIT entirely. Only rtk hook claude writes the audit log. So after the restart the hook was demonstrably rewriting (ls -la came back in rtk's compact form) while rtk hook-audit still reported "No audit log found". The instrument I had just enabled was disabled by the change I made alongside it, and I only caught it because I checked the log instead of assuming it. The wrapper now execs rtk hook claude, keeps the script-path registration, and writes the log. Verified end to end.