Token Optimisation for AIOS

Section 01

Why Optimise on a Flat Plan?

Your bill doesn't drop when you optimise tokens on a subscription. So why bother? Because the win you feel is real: "I don't hit the weekly cap anymore" and "sessions last longer." Every token saved delays throttle, extends context before /compact, and becomes real dollars the moment you exceed caps or switch to API.

~$400

Actual subscription paid
(4 months)

$3,053

Shadow price — what those tokens would cost on API rates

7.5×

Ratio — the target is getting yours above 2× first

💡

What is "shadow price"? Tools like ccusage read your local JSONL logs and multiply every token by its API rate. The $3,053 figure is what those tokens would have cost on pay-per-token API billing — a hypothetical comparison, not a bill. It's how you measure the value flowing through your flat-rate plan.

Your subscription

Flat monthly fee

$20 / $100 / $200 per month, fixed
5h rolling session window + weekly cap
Bill doesn't move with token count
Win = sessions run longer, caps hit less often

API / what tools report

Metered pay-per-token

Every token has a price — linear cost
No caps — but bill can balloon fast
Where ccusage shadow prices come from
Savings become real the moment you exceed subscription caps or switch to API

Section 02

The 4 Levers — All Free, All Stack

Four tools that work together. None cost anything. Installing all four takes about 90 minutes. If you only do one thing: install RTK. Five minutes, immediate win.

1

ccusage

Measure

Reads your local JSONL logs and calculates shadow prices. The instrument panel — you can't optimise what you don't measure.

$3,053 equivalent over 4 months measured

2

RTK

Strip tool output

PreToolUse hook that strips raw tool output before it enters context. Community-validated: ~89% of CLI noise tokens eliminated. Zero friction — every Bash call auto-optimised.

13.5M tokens saved over 8,865 commands

3

context-mode

Sandbox tool output

Claude plugin / MCP server. Tool output goes to a sandbox, not the main context. Queryable when needed. Preserves items across compactions — solving the "context loss" problem.

105 items preserved across compactions · 56% token reduction

4

settings.json

Tune the defaults

Four environment variables that change the default behaviour. Sonnet instead of Opus, capped thinking, early autocompact, Haiku subagents. Two minutes to copy and paste.

~70% thinking-cost reduction from thinking cap alone

🔗

They stack. RTK strips what enters the context. context-mode prevents the rest from entering at all. settings.json reduces cost per token. ccusage proves the savings. Together they compound — installing all four in order is the path to 2×+ ratio.

Section 03

Where Tokens Go — The Hidden Costs

Most people think context = the chat. It's way more than that. Everything below is loaded on every turn and stays in context until /clear or /compact.

Loaded on every turn

Raw tool output — ls, grep, git diff, file reads. Every line stays until cleared.
CLAUDE.md — loaded on every prompt, forever. Every line you add costs tokens every message.
MCP tool definitions — >10 MCPs can cut effective window from 200k to 70k. (April 2026: auto-deferred if >10% of context, but still matters.)
Hidden thinking tokens — default 31,999. You're paying for extended thinking even when you don't need it.
System prompts + conversation history — grows with every exchange.
Compaction residue — compaction at 95% (default) fires after you've already paid for everything.

⚠ Opus 4.7 tokenizer trap: Opus 4.7 costs ~35% more tokens for identical text compared to Opus 4.6. If you upgraded silently (you did), you're paying 35% more on every prompt. Invisible. Nobody flags it. Always pair Opus 4.7 with CLAUDE_CODE_EFFORT_LEVEL=medium.

Section 04

The Baseline settings.json — 2-Minute Change

Copy this into ~/.claude/settings.json. If you copy nothing else from this workshop, copy this. It changes four defaults that are costing you tokens on every prompt.

{

  "model": "sonnet",

  "env": {

    "MAX_THINKING_TOKENS": "8000",

    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "60",

    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",

    "CLAUDE_CODE_EFFORT_LEVEL": "medium"

  }

}

Line	Why it matters
model: sonnet	Sonnet 4.6 matches Opus 4.6 on most coding at ~1/5 the input price. Escalate per-task with `/model opus` or `/model opusplan` when you actually need reasoning.
MAX_THINKING_TOKENS: 8000	Default is 31,999. This single setting gives ~70% thinking-cost reduction. Thinking bills at output rate — most tasks don't need 32k thinking tokens.
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: 60	Default fires at 95% — by then you've already paid for everything. Compact at 60% for cleaner context and earlier refresh. Reframe: autocompact is a failure mode, not a safety net.
CLAUDE_CODE_SUBAGENT_MODEL: haiku	~80% cheaper on Task tool calls. Haiku handles most subagent work fine. The savings compound fast on any workflow using parallel agents.
CLAUDE_CODE_EFFORT_LEVEL: medium	Prevents unexpected xhigh thinking spikes on Opus 4.7. Critical if you're using Opus 4.7 for anything — without this, thinking can explode unexpectedly.

Section 05

.claudeignore — 50-70% Less File-Scanning Waste

Without a .claudeignore at workspace root, every grep walks node_modules, every Read can pull a lockfile. Add this file and eliminate low-signal bulk from every scan.

# .claudeignore — place at workspace root

node_modules/

.git/

.venv/

dist/

*.lock

*.log

data/*.db

outputs/playwright/

📁

Start with the block above, then grow it. A mature .claudeignore has 60+ patterns sectioned by category. Consider adding an /optimize-context skill that scans your repo for large/low-signal files and suggests new patterns to add. Every pattern you add is tokens saved on every scan, forever.

Section 06

Cache Economics — The "Free Money" Lever Nobody Uses

Prompt caching is automatic in Claude Code — you don't enable it, you just need to not break it. The economics are stark enough that understanding them changes how you work.

Cache write: $10/MTok — one-time cost to write a prefix to cache.
Cache hit: $0.50/MTok — 10x cheaper than fresh input ($5/MTok). For a session-length of work, one write amortises across the whole thing.
1-hour TTL now available (April 2026) — alongside the 5-minute TTL. Use 1h TTL for long sessions to avoid cache expiry mid-flow.
What breaks cache: Rewriting CLAUDE.md or system prompts mid-session. Adding new text before existing cached content. Don't modify the prefix during a session — any change forces a full re-tokenize and re-write.
Cache miss from idle: Pause >5 minutes (with 5-min TTL) and the prefix re-tokenizes. Fix: don't pause mid-flow on the default TTL. Or switch to the 1h TTL for long sessions.

Section 07

2026 Pricing Cheat Sheet

5× cost delta between Opus and Sonnet on input. The decision of which model to use is not aesthetic — it has direct financial consequences. Pick deliberately.

Model	Input / MTok	Output / MTok	Best for
Haiku 4.5	$1	$5	Subagents, greps, simple lookups
Sonnet 4.6 ★	$3	$15	Default. Coding, refactoring, routine tasks. Matches Opus 4.6 on most coding.
Opus 4.6	$15	$75	Complex architecture. Legacy but still active.
Opus 4.7	$5	$25	Heavy reasoning — but ~35% tokenizer inflation vs 4.6. Always pair with EFFORT_LEVEL=medium.

⚠️

The Opus habit kills budgets. Most people leave it on Opus all the time and wonder why they're hitting limits. Sonnet handles 80%+ of coding tasks. Start in Sonnet, escalate to Opus only when you hit a reasoning gap, come back to Sonnet after. The savings are immediate.

Section 08

Model Routing — The Right Tool Per Task

Task	Command	Why
Planning / architecture	/model opus	Complex reasoning needs the bigger model. Use it deliberately for this phase only.
Execution / coding	/model sonnet	Default. Sonnet matches Opus on most coding at 1/5 the cost.
Plan then execute in one session	/model opusplan	Plans in Opus, executes in Sonnet. ~40% cheaper than staying on full Opus throughout.
Subagents (Task tool)	SUBAGENT_MODEL=haiku	~80% cheaper. Set once in settings.json, applies to every subagent call automatically.

Section 09

The Live HUD — See It to Save It

The psychological shift from "I wonder how much I've spent" to "I have $5.80 left today" changes behaviour more than any config tweak. Install the status line so you can see burn rate in real time.

# Install and wire up — accept ccusage install when prompted

npx ccstatusline@latest

# Pin the version in settings.json — never leave @latest

"statusLine": {

  "type": "command",

  "command": "npx -y ccstatusline@2.2.8",

  "padding": 0

}

ccstatusline — 1.1K stars, interactive TUI. 25+ widgets: model, context %, session cost, daily cost, 5h block burn, git state, token counts. Auto-wires into settings.json.
ccusage — 13K stars, the data layer ccstatusline runs on. Accept the install prompt when you run ccstatusline for the first time.
cc-budget (optional) — npm i -g cc-budget. Sets a hard daily cap with traffic-light readout. 25 stars — bleeding-edge, not a core recommendation. Start with ccstatusline + ccusage; add cc-budget when you want a hard cap.

Section 10

RTK + context-mode — The Two Plugins That Matter

RTK — strips raw tool output before it enters context

# Install — always use --hook-only

brew install rtk

rtk init -g --hook-only

rtk gain # check your savings

🚨

CRITICAL: always use --hook-only. Without it, RTK adds ~400 tokens per prompt and defeats the entire purpose. This is the most common installation mistake.

~89% of CLI noise tokens stripped (community-validated). Works via PreToolUse hook — every Bash call is auto-optimised with zero friction.
68% total input-token reduction over 8,865 commands = 13.5M tokens saved across 6 weeks of real usage.

context-mode — sandboxes tool output, preserves state

Claude plugin / MCP server. Tool output goes to a sandbox — not the main context. Queryable via ctx_search and ctx_execute when the AI needs to reference it.
One 5.4h session (76 calls): 1.5 MB processed, 857 KB stayed in sandbox — never hit context. 56% token reduction. 105 items preserved across compactions.
Solves the "context loss after /compact" problem. Items in the sandbox survive compaction and are available when referenced.

🔗

They do different jobs and stack. RTK trims what enters context (strips the noise before it lands). context-mode prevents tool output from entering context at all (sandboxes it instead). Install both — together they eliminate the two largest token sinks in any active session.

Section 11

Habits — No Config Fixes a Bad Habit

1

Phase separation — Explore → /clear → Implement

Planning context is a liability when you're implementing. The plan file is the handoff, not the chat history. /clear between phases is the most impactful single habit change.

2

Batch prompts into single messages

Every message triggers a full context re-read. Five short messages cost 5× more than one batched message. Think before you type — combine the question, not the keystrokes.

3

Compact timing — never mid-implementation

Compact at logical breakpoints (after exploration, after milestones). Autocompact fires at 95% by default — by then you've paid for everything. Override to 60%. Reframe: autocompact firing is a failure, not a feature.

4

Surgical file references

Don't read 500 lines when you need 40. Grep first to find the relevant line, then Read with offset and limit. Every unnecessary line read is tokens paid on every subsequent turn.

5

Subagents as context firewalls — but cap concurrency

Research in a subagent = that research never enters your main context. But unbounded parallel fan-out is how $47K bills happen. One dev's case: 80-85% of his spend was Opus in subagents he forgot to cap. Always set a concurrency limit.

Section 12

8 Spike Patterns — Know What's Bleeding You

1

Context resubmission

Every message re-sends full conversation history. Fix: /clear between phases

2

Autocompact cascade

Compaction at 95% drops critical context mid-task. Fix: override to 60%

3

Subagent fan-out

5 agents = 5× context overhead. Fix: Haiku subagents + cap concurrency

4

Long session tool accumulation

Tool output accumulates across a session. Fix: RTK + fresh session every 2-3 hours

5

MCP bloat

Each MCP's tool schema loads on every message. Fix: prune to <10 MCPs, prefer skills + CLIs. (April 2026: Claude Code auto-defers MCPs >10% of context — advice is softer now, but still prune.)

6

Cache expiry

Idle >5 min forces prefix re-tokenize. Fix: don't pause mid-flow; use 1h TTL for long sessions

7

Extended thinking default (Opus 4.7 xhigh)

Thinking bills at output rate. Fix: EFFORT_LEVEL=medium

8

Version regression

Opus 4.7 tokenizer ~35% more verbose than 4.6. Fix: default Sonnet 4.6

Section 13

CLAUDE.md Budget — Every Line Costs Every Turn

CLAUDE.md is loaded on every single prompt. Every line you add costs tokens on every message for the life of the session. Treat it as an index, not a dump.

<50

Gold standard
~750 tokens

<80

Target for
complex AIOS

150

Practical
ceiling

200

Anthropic
hard ceiling

📋

Use CLAUDE.md as an index, not a dump. Trigger keywords → file paths. The detail lives in .claude/rules/, skill SKILL.md, or docs/. CLAUDE.md just needs enough to orient Claude — workspace structure, available commands, and a few pointer lines. Nothing more.

Setup Checklist

One-Time Setup — 90 Minutes Total

Order matters: settings.json first (free, immediate), RTK second (5 min), context-mode third.

Edit ~/.claude/settings.json with the baseline config above2 minutes. Immediate impact on every session.

Install RTK: brew install rtk && rtk init -g --hook-only5 minutes. Never omit --hook-only.

Install context-mode pluginFrom github.com/mksglu/context-mode

Add .claudeignore to workspace rootCopy the block from Section 05. Grow it over time.

Run npx ccstatusline@latest, accept ccusage install, pick widgets, then pin the version in settings.jsonDon't leave @latest — pin to specific version.

npm i -g cc-budget, set a daily cap (optional)Only after ccstatusline is working.

Trim CLAUDE.md to <80 linesAudit what's in there. Move detail to .claude/rules/ or docs/.

Measure weekly:

ccusage # per-block token + cost detail

ccusage block # current 5h block burn

rtk gain # tokens RTK is saving

/ctx-stats # context-mode savings

/usage # weekly headline % (too coarse for per-task)

Per-session habits:

Start in plan mode for non-trivial tasks

/clear between phases (explore → implement)

Batch related prompts into single messages

Reference files surgically (line ranges, function names, not full files)

Compact at logical breakpoints only; never mid-implementation

Escalate to Opus only when needed; return to Sonnet after

Glance at statusline — burn-rate spike or budget <20% → stop and diagnose

Key Takeaways

What to Remember

Expected results after full implementation: sessions run ~2.5× longer before hitting limits, ~60–70% overall token spend reduction, better quality in long sessions, ratio above 2× on the paid vs API-equivalent comparison.

Takeaway 01

Defaults are the problem, not you

60–90% of wasted tokens come from default settings that ship with Claude Code. The first 2-minute fix — copying the baseline settings.json — eliminates most of it before you do anything else.

Takeaway 02

If you only do one thing: install RTK

5-minute install. ~89% of CLI noise tokens stripped. 68% total input-token reduction observed over real usage. The single highest-impact low-effort change available. Use --hook-only.

Takeaway 03

Sonnet handles 80%+ of coding

Most people stay on Opus all the time. Sonnet matches Opus 4.6 on most coding at ~1/5 the cost. Escalate to Opus for reasoning-heavy tasks, come back to Sonnet after. This single habit change is worth more than all the config tweaks combined.

Takeaway 04

Autocompact at 95% is a failure mode

By the time it fires at default, you've already paid for everything. Override to 60%. Compact deliberately at logical breakpoints. The goal is to compact before the context becomes expensive, not after.

Takeaway 05

CLAUDE.md is loaded every turn

Every line you add costs tokens on every single message for the life of the session. Target <80 lines. Use it as an index — trigger keywords → paths. Move all detail to .claude/rules/ or docs/.

Takeaway 06

Measure before you optimise

You cannot optimise what you don't measure. Run ccusage weekly. Check rtk gain. Look at /ctx-stats. 10 minutes of measurement beats hours of guessing which optimisations are actually working.

References

Tools Referenced

RTK: rtk-ai.app — brew install rtk && rtk init -g --hook-only
context-mode: github.com/mksglu/context-mode
ccusage: npm i -g ccusage (13K stars)
ccstatusline: github.com/sirmalloc/ccstatusline (1.1K stars)
cc-budget: github.com/boyand/cc-budget (optional hard cap, 25 stars)
Questions: valera@aaaaccelerator.com

📄

Companion materials: The full handout (handout-token-optimisation.md) and slides PDF (handout-slides.pdf) were distributed with the original workshop. The handout is the definitive reference — copy-paste ready config blocks, all checklists, and pricing tables in one document for use inside your Claude Code workspace.

Continue Learning