Mastering Claude Code: The Token-Efficiency Playbook

How I cut my Claude Code token usage by 60% without sacrificing output quality — the exact system I use every day.

The Real Cost: Why Token Discipline Matters

Most developers blame the model when their AI coding bill spikes. The real problem is almost always the workflow. I have watched teams burn through their entire monthly allocation in days — not because they coded more, but because they let context bloat, never cleared sessions, and ran everything on the most expensive model.

Token costs scale with context size: every message you send carries the entire conversation history, all loaded files, every MCP server definition, and your CLAUDE.md configuration. A one-line question in a session open all day still pays for everything that came before it.

The Four Layers of Token Efficiency

I organise my Claude Code cost-control system into four progressive layers. Each builds on the last. Start at the top and work down — the earlier layers give the biggest return for the least effort.

Layer 1: Observe Your Usage

Before optimising anything, I check where my tokens are actually going. Claude Code gives you three commands for this, and I use all three at natural breakpoints — not after every prompt, but when a session starts feeling slow, after a large tool run, or before handing off.

Layer 2: Build a Lean CLAUDE.md

CLAUDE.md is sent on every single API call. Every word in it costs tokens on every message. I treat it as a tight index — only essentials, not an operations manual. Move rare instructions into skills; they load on demand.

# Project commands
build: npm run build
test:  npm test -- --reporter=dot
lint:  npm run lint

# Directories
src/       — app code
tests/     — test files
.planning/ — specs and ADRs (read only)

# Hard constraints
Never edit vendor/ or generated/
Always run lint before committing

# Rare workflows → use skills
/review, /deploy, /release

The goal is ruthless compression. If a rule is not violated at least once per week, it probably does not belong in CLAUDE.md. Put it in a skill instead — it will load on demand and cost nothing when it is not needed.

Scoped Inputs: Filter Before Claude Reads

The other side of base context reduction is what you feed Claude at runtime. Most developers hand over entire log files, full diffs, and broad directory scans. This is almost always wasteful.

This pattern works because it does not hide data — it changes the first slice Claude sees. If that slice is insufficient, ask for the next section. Start narrow, widen on evidence.

Layer 3: /clear vs /compact — Know the Difference

These two commands solve different problems, and confusing them is the most common mistake I see. /clear starts a brand-new session with zero context. /compact summarises the current session to free space while keeping continuity.

The Cache You Lose When You Sleep

Anthropic caches the token prefixes that repeat between calls, and reading from cache costs a fraction of the normal price. But that cache has a limited lifespan — if you pause for more than an hour, it evaporates.

When you resume an old conversation after the cache expires, the entire context has to be reprocessed from scratch at full price. You are effectively paying for the same conversation twice. This is why I start a new conversation each day rather than trying to pick up yesterday's thread.

Layer 4: Right Model for the Right Job

The single highest-impact change I made was setting Sonnet as my default model instead of Opus. The difference between a refactor on Opus and the same refactor on Sonnet can be $5 versus $0.50 — on a single task. Over a month, it compounds dramatically.

Subagents and Skills Architecture

Each subagent works with its own context window, separate from the main conversation. When it finishes, only a summary returns. All intermediate work — file reads, searches, tests — stays isolated.

This means your main conversation stays clean for much longer. You delay or avoid compaction entirely. Skills work similarly: they are reusable instructions that load only when invoked, unlike CLAUDE.md which is always present.

My Pre-Flight Checklist

I run through these steps before every significant coding session. It takes 30 seconds and saves thousands of tokens — and often hours of degraded output from a bloated context.

Hooks: Automate the Discipline

Hooks are shell commands that run at fixed Claude Code lifecycle events. The most powerful token-saving hook intercepts test output and filters it down to just the failures — before Claude ever sees it.

// In settings.json → hooks → PreToolUse
{
  "matcher": "Bash",
  "hooks": [{
    "type": "command",
    "command": "~/.claude/hooks/filter-test-output.sh"
  }]
}

// The script: intercepts test commands,
// filters to failures, keeps full log on disk

Other high-value hooks: filter git log output to recent commits, truncate large file reads, strip verbose compiler warnings. The principle is always the same: Claude needs evidence, not a dump.