Zo bespaar je tokens in Claude Code en Codex met RTK en Headroom

Herschreven op 3 oktober 2026. De eerste versie van dit artikel verscheen op 8 september en beschreef vier tools op basis van één ochtend meten. Na vier weken meten klopte een groot deel daarvan niet meer. Codex loopt niet meer via Headroom, Caveman en Ponytail staan standaard uit, en de besparing van Headroom komt uit een andere hoek dan ik toen dacht. Daarom heb ik het artikel opnieuw geschreven, met nieuwe cijfers en een nieuwe prompt.

Waar de tokens heen gaan

Claude Code en Codex draaien bij mij op een abonnement. Ik betaal een vast bedrag per maand, en hoeveel ik kan doen wordt begrensd door een gebruikslimiet. Op drukke dagen loop ik daar halverwege de middag tegenaan.

Een coding agent stuurt bij elke stap het hele gesprek opnieuw naar het model. Dat zijn de instructies, de beschrijvingen van alle tools die de agent kan gebruiken, en alles wat er in de sessie al is gezegd en gelezen. Het grootste deel komt uit de prompt cache van de provider en is daardoor goedkoper, maar het telt wel mee. In de afgelopen week stuurde Claude Code bij mij per stap meestal rond de 166.000 tokens mee. Dat is de mediaan over ruim 19.000 verzoeken.

Ik heb ook gekeken wat er in die gesprekken staat. In ruim 120 sessies van Claude Code uit de afgelopen week was 37% van de tekst uitvoer van shellcommando's, zoals git diff of een testrun. Nog eens 18% kwam van MCP-tools, zoals de browserkoppeling, en 8% van gelezen bestanden. De aanroepen van de agent zelf, waaronder de inhoud van bestanden die hij schrijft, waren 27%. Mijn vragen en de antwoorden van Claude waren samen 9%.

Daarnaast staat er bij de start van elke sessie al een flinke hoeveelheid tekst in de context, voordat ik iets heb getypt: de systeeminstructies van Claude Code, de tooldefinities, mijn eigen instructiebestanden en wat plugins toevoegen. Bij mij is dat rond de 50.000 tokens. Ook dat gaat bij elke stap opnieuw mee.

Er zijn dus drie plekken waar besparen zin heeft: de uitvoer van shellcommando's, de tooldefinities, en wat er bij de start van een sessie wordt meegestuurd. Voor elk daarvan gebruik ik iets anders.

RTK maakt shell-uitvoer kleiner

RTK is een programma voor de commandoregel dat bekende commando's uitvoert en hun uitvoer inkort voordat de agent die leest. rtk git diff geeft dezelfde wijzigingen als git diff, met minder witregels, herhaling en opmaak eromheen. RTK kent onder meer git, gh, rg, grep, ls, pnpm, docker en de gangbare testrunners.

De agent hoeft RTK niet te kennen. RTK installeert een hook die elk shellcommando bekijkt voordat het wordt uitgevoerd. Kent RTK het commando, dan maakt de hook er de RTK-variant van. In Claude Code zet rtk init -g die hook neer, in Codex doet rtk init -g --codex dat vanaf versie 0.50.

Bij mijn eerste opzet voor Codex ging dat mis. Een instructiebestand vertelde Codex om zelf rtk voor elk commando te zetten. Een commando dat al met rtk begint, laat de hook met rust. Op 9 september bespaarde RTK bij Codex daardoor maar 1,7%. Sinds de hook het werk doet en die instructie weg is, is dat 26%, gemeten sinds 1 oktober.

Sinds 10 september heeft RTK op mijn laptop ruim 28.000 commando's ingekort. Die leverden samen 7,3 miljoen tokens uitvoer op, en daarvan haalde RTK 2,65 miljoen weg: 36%. In de afgelopen week was dat 33%. Ik tel hier alleen commando's met minder dan 50.000 tokens uitvoer, en laat rtk read en rtk lint weg. Waarom lees je hieronder.

Hoeveel RTK weghaalt, verschilt sterk per commando. Bij lijsten en zoekresultaten is veel weg te halen: 69% bij ls en 41% bij rg. De uitvoer van git status is meestal al kort, en git show bestaat vooral uit code. Daar blijft weinig te besparen.

rtk gain, het overzicht van RTK zelf, meldt bij mij 86%. Dat getal is te hoog. Een rtk read van een heel groot bestand telt als volledig bespaard, en een paar van die aanroepen bepalen dan het hele totaal. rtk lint rekent het volledige rapport van eslint als invoer, ook als eslint niks vindt. Elke schone lintrun telt daardoor als bijna 100% bespaard. Daarom laat ik die twee weg en tel ik alleen commando's onder de 50.000 tokens.

Headroom houdt tooldefinities buiten de context

Headroom is een proxy die lokaal draait, tussen Claude Code en de API van Anthropic. Claude Code wijst ernaar via ANTHROPIC_BASE_URL. Headroom luistert alleen op 127.0.0.1:8787 en draait als achtergronddienst, dus hij staat al aan als ik een terminal open. Claude Code logt gewoon in met het abonnement. Er is nergens een API-sleutel nodig.

Headroom is gemaakt om verzoeken te comprimeren, en zo gebruikte ik hem eerst ook. De besparing komt bij mij nu bijna helemaal uit iets anders. Claude Code stuurt bij elk verzoek de beschrijvingen mee van de tools die het kan gebruiken. Headroom laat een vaste kern van tools staan, zoals Bash, Read, Edit en Grep. De overige markeert hij als uitgesteld, en hij voegt een zoektool toe. Anthropic laat uitgestelde tools dan buiten de context, tot het model ernaar zoekt. Alle tools blijven bruikbaar.

Sinds Headroom op 30 september opnieuw is gestart, telde hij 4.159 verzoeken met samen 850 miljoen tokens. Daarvan haalde hij er 30 miljoen weg, 3,6%. Daarvan kwam 27,6 miljoen van uitgestelde tooldefinities: bij de 3.184 verzoeken waar hij tools uitstelde, gemiddeld zo'n 8.700 tokens per verzoek. Het comprimeren van berichten leverde 2,6 miljoen op, 0,3%. Dit zijn de tellingen van Headroom zelf. Vanuit Claude Code kan ik ze niet los controleren.

De compressie staat bewust voorzichtig afgesteld. Headroom heeft standen die meer weghalen, maar die vervangen soms een stuk tekst door een verwijzing (<<ccr:...>>). Bij Codex gebeurde dat in 16 van de 428 sessies tussen 5 en 10 september, en Codex had geen manier om die verwijzingen op te halen. Het las dan een bestand zonder de inhoud te zien. Daarom draait Headroom nu lossless: gelezen bestanden en shell-uitvoer gaan ongewijzigd door, en de rest wordt alleen ingekort als er niets verloren gaat.

Codex loopt niet meer via Headroom. Met de lossless instellingen heb ik het van 28 september tot 1 oktober opnieuw geprobeerd, en dat leverde 0,8% op. Het uitstellen van tooldefinities, waar bij Claude Code bijna alle winst vandaan komt, doet Headroom bij Codex niet. Andere gebruikers meldden dat Codex-sessies daardoor vastliepen, en Codex houdt zijn tooldefinities al zelf buiten de context zodra ze te veel ruimte innemen. Headroom had bij Codex dus niets meer uit te stellen.

Headroom heeft ook nadelen. Remote Control van Claude Code werkt niet met een eigen ANTHROPIC_BASE_URL. Claude Desktop gaat langs de proxy heen. En elk verzoek loopt via een extra stap, die bij mij gemiddeld 117 milliseconden kost.

Minder meesturen bij de start

De derde plek is de tekst die bij de start van elke sessie in de context komt. Ik had drie plugins aanstaan die daar instructies aan toevoegden: Caveman voor kortere antwoorden, Ponytail om de agent minder code te laten schrijven, en Superpowers met werkwijzen voor plannen en testen.

Om te meten wat dat kost, heb ik Claude Code zonder interactie gestart in een lege map, met en zonder die drie plugins. Met plugins was de eerste aanvraag 37.900 en 40.900 tokens groot, zonder plugins 32.900 tot 34.900 tokens. Dat is ongeveer 6.000 tokens minder, en dat scheelt bij elke stap van een sessie. Of de plugins dat terugverdienden, kon ik niet aantonen. Vragen en antwoorden zijn samen 9% van een gesprek, dus kortere antwoorden van Caveman schelen weinig in de context.

Sinds 28 september staan alle drie standaard uit. Caveman is nog geïnstalleerd, en ik zet het per sessie aan met /caveman als ik dat wil. Het belangrijkste idee van Ponytail staat nu als één regel in mijn globale instructies: kies de kleinste complete oplossing, eerst bestaande code, dan de standaardbibliotheek, het platform en geïnstalleerde dependencies, en pas daarna nieuwe code.

Het loont om af en toe te kijken wat er verder bij de start wordt toegevoegd. Bij mij voegt de Vercel-plugin in de meeste sessies zo'n 8.000 tekens toe, ook in projecten zonder Vercel. En rtk init -g zette een verwijzing naar de RTK-instructies in mijn CLAUDE.md, terwijl Claude Code die al via een ander instructiebestand laadde. Die instructies stonden er dus twee keer in.

Waar ik tegenaan liep

• Codex sloeg hooks zonder melding over. Codex voert alleen hooks uit die je hebt goedgekeurd, en onthoudt die goedkeuring per pad van hooks.json. Ik gebruik Codex met twee accounts, elk met een eigen map. Onder het tweede account draaide geen enkele hook: 49 sessies zonder RTK. Ik heb de goedkeuringen ook voor die map toegevoegd.
• `rtk init -g --codex` voegt een nieuwe hook toe. Codex heeft die nog niet goedgekeurd en slaat hem over. Controleer na elke keer dat je het commando draait of Codex de hook echt uitvoert.
• `headroom install restart` kan op macOS vastlopen als launchd de dienst tegelijk weghaalt. headroom install start --profile default lost het op. Controleer daarna /readyz. Dit staat in issue #1289, inmiddels gesloten, maar ik liep er op 0.37.0 nog tegenaan.
• Controleer of het verkeer echt via de proxy loopt. Een client die er langs praat, bespaart niks en meldt ook niks.
• Tel de percentages van RTK en Headroom niet bij elkaar op. Headroom rekent over elk verzoek, RTK alleen over de shell-uitvoer die hij heeft ingekort. Die overlappen.

Zo meet ik het

Headroom houdt zijn besparingen 30 dagen bij. Om een langere reeks te hebben, kopieert een klein script elk uur de gegevens van elke besparing naar een eigen archief: tijdstip, client, model en aantallen tokens. Prompts en antwoorden komen er niet in. RTK houdt zijn eigen geschiedenis bij in een database, waar ik de commando's onder de 50.000 tokens uit filter.

Een shellfunctie, usage --savings, zet beide naast elkaar, samen met welke plugins aanstaan. Ik reken niet om naar euro's. Op een abonnement is dat bedrag een schatting, en tokens kan ik tellen.

De prompt

Wil je dit zelf inrichten? Plak de prompt hieronder in Claude Code of Codex, op de Mac die je wilt instellen. Hij gaat uit van macOS met Homebrew en uv. Bij een andere opzet moet je de paden aanpassen.

Set up a token-saving stack for my Claude Code and Codex CLI installs. Both log in with a subscription. Do not add, request or store an API key anywhere. Change only global config on this Mac, never a project repository. Show me every config diff before you apply it.

1. RTK (shell output compression, Claude Code and Codex)
   - brew install rtk (version 0.50 or newer).
   - Claude Code: rtk init -g, then confirm a PreToolUse hook runs "rtk hook claude". Check that my global CLAUDE.md and AGENTS.md load the RTK instructions only once.
   - Codex: rtk init -g --codex. It adds a PreToolUse hook that rewrites shell commands. Codex only runs hooks I have approved, so open Codex and approve the new hook. If an older rtk hook entry exists, keep one. If I use more than one CODEX_HOME directory, approve the hook in each.
   - Do not tell either agent to type rtk itself. The hook does not rewrite a command that already starts with rtk.
   - Verify: run git status from Claude Code and from Codex, and confirm both show up in rtk gain.

2. Headroom (request proxy, Claude Code only)
   - Install: uv tool install "headroom-ai[proxy,code]"
   - Deploy as a persistent local service on 127.0.0.1:8787 for Claude Code:
     headroom install apply --preset persistent-service --scope provider --providers manual --target claude --mode cache --backend anthropic --no-telemetry --code-aware
   - Do not enable memory or telemetry. On the service, set HEADROOM_DISABLE_KOMPRESS=1, HEADROOM_LOSSLESS=1, HEADROOM_LOSSLESS_ONLY=1, HEADROOM_PROTECT_READS=1 and HEADROOM_PROTECT_TOOL_RESULTS=Bash, so file reads and shell output pass through untouched. Leave tool search deferral on (HEADROOM_TOOL_SEARCH, on by default).
   - Do not route Codex through Headroom. Lossless mode saved under 1% for Codex, and its tool search deferral does not apply to Codex.
   - Expected result: ~/.claude/settings.json has env ANTHROPIC_BASE_URL=http://127.0.0.1:8787.
   - Verify with headroom install status and curl http://127.0.0.1:8787/readyz, then send one real Claude Code request and confirm it appears in headroom savings.
   - If restart races launchd on macOS, use headroom install start --profile default.
   - Tell me that Claude Code Remote Control stops working with a custom ANTHROPIC_BASE_URL.

3. Startup context
   - List everything that adds text to every new Claude Code and Codex session: plugins, SessionStart hooks, and files imported from CLAUDE.md and AGENTS.md, with an approximate size for each. Propose what to switch off, and change nothing without my approval.
   - Caveman (optional): claude plugin marketplace add JuliusBrussee/caveman, then claude plugin install caveman@caveman, with "defaultMode": "off" in ~/.config/caveman/config.json so it only runs after I type /caveman. Do NOT install the Caveman proxy.
   - Instead of the Ponytail plugin, add this one line to my global CLAUDE.md and AGENTS.md: "Choose the smallest complete solution: existing code, standard library, native platform, installed dependency, then new code."

4. Measurement
   - Add a usage --savings shell function that prints: Headroom today and 30 days (headroom savings --json), a durable per-client archive total, RTK totals (rtk gain --format json), and which Caveman mode is active.
   - Report RTK twice: all commands, and only commands under 50,000 input tokens excluding rtk read and rtk lint. A single rtk read of a huge file counts as fully saved, and rtk lint counts eslint's whole report as input.
   - Write ~/.local/bin/llm-compression-usage: copy new events from ~/.headroom/savings_events.jsonl into ~/.local/share/llm-usage/headroom-events.jsonl with mode 0600, deduplicated, keeping only timestamp, client, model, token counts, cost field and source. Skip lines that do not parse instead of stopping. Never store prompts or responses. Run it hourly and at login through a launchd agent.
   - Rules: tokens only, no estimated dollar or euro savings for any tool. Keep Headroom and RTK totals separate and label why. Do not invent session attribution between tools. Add a small test file for the helper covering deduplication, broken lines and field filtering.

5. Finish by running usage --savings in a fresh login shell and reporting exactly what passed, what failed and what you could not verify.

Wat ik zou aanraden

Begin met RTK. Het werkt voor Claude Code en Codex, je merkt er tijdens het werk niets van, en het haalt ongeveer een derde van de shell-uitvoer weg. Kijk daarna wat er bij de start van een sessie in de context komt, en zet uit wat je niet gebruikt. Headroom is vooral nuttig als je in Claude Code veel tools of MCP-koppelingen hebt, en kost je Remote Control.

Kanttekeningen

• Eén laptop, één gebruiker. Alle cijfers komen van mijn eigen MacBook en mijn eigen projecten, gemeten tussen 10 september en 3 oktober 2026. Bij jou kunnen ze anders uitvallen.
• De tools tellen zelf. RTK en Headroom berekenen hun besparing zelf. Ik heb de cijfers uit hun logs gehaald, maar kan ze niet onafhankelijk controleren.
• De samenstelling van een sessie is gemeten op tekst. Afbeeldingen en het denkwerk van het model tellen daarin niet mee.
• De grootste factor heb ik nog niet aangepakt. Hoe langer een sessie duurt, hoe meer elke stap meestuurt. Daar schrijf ik een volgend stuk over.