Cutting Claude Code token usage, the parts that actually matter

Every message you send in a Claude Code session re-sends what's already in context: the system prompt, your CLAUDE.md, MCP server instructions, and every file and command output from earlier in the session. So the cheapest token is the one that never enters context. Here's what's worth doing, roughly in order of payoff.

1. Look before you optimize: /context

Run /context in a session. It shows what's taking up the window right now. Run it again after you add an MCP server or grow your CLAUDE.md, and you'll see the cost directly. On subscription plans, /usage also breaks down recent usage by skills, subagents, plugins and MCP servers (costs docs).

2. Keep the always-loaded part small

• CLAUDE.md loads at the start of every session. Anthropic's guidance is to keep it under 200 lines. Move workflow-specific instructions (how to do a release, how to write a migration) into skills, which load only when used.
• MCP servers you don't use still cost something. Tool definitions are deferred by default, but tool names and server instructions still enter context. Disable idle servers with /mcp. Where a CLI exists (gh, aws), Claude can often use it instead.

3. Reset instead of dragging history along

• /clear between unrelated tasks. Stale context gets re-sent on every message. Use /rename first if you want to /resume that session later.
• /compact Focus on X at natural breakpoints, with an instruction about what to keep. If you don't need continuity, /clear is cheaper than compacting.

4. Know the built-in limits, so you don't fight them

Claude Code already caps the worst cases (tools reference):

• Read returns at most 25,000 tokens per call and refuses a whole file over 256 KB, so big files get read in pages with offset/limit. Since v2.1.296, Claude can pass allow_large: true to read a whole file sized against the context you have left.
• Bash output that succeeds comes back inline up to about 30,000 characters. Past that, Claude gets a file path and a 2,000-character preview. bashOutputMaxChars raises that ceiling, but raising it also means more context per command.

So the real waste isn't a single 5 MB read; Claude Code stops that. It's the many medium reads that are allowed but useless. A 70 KB package-lock.json, a minified bundle, a source map, or a file deep in node_modules is each up to 25k tokens of text the agent rarely needed more than one line of. And it stays in context for the rest of the session.

5. Block the useless reads with a hook

A PreToolUse hook runs before every tool call and can deny it with a reason the model reads. That makes it a good place to say "don't read the lockfile, grep it":

agent wants to:  Read package-lock.json                 (68 KB)
hook:            DENY  `package-lock.json` is a 68 KB lockfile. To check a version:
                       grep -n -A3 'package-name' package-lock.json
agent wants to:  Read package-lock.json offset=1 limit=200
hook:            (allowed)

The rules that pay off:

• Deny a full Read (no limit, or a huge one) of lockfiles, *.min.js/*.min.css, *.map, and anything under node_modules, .venv, .next, coverage, etc.
• Apply the same check to cat/less in Bash.
• Always allow files under a few KB, targeted reads (offset/limit), and Grep. That way the agent can still answer "which version of react is installed?" in one cheap call.
• Deny binaries (archives, .sqlite, model weights) outright. Their bytes are useless as context.

I published this as token-diet-lite: one stdlib Python file, MIT. In Claude Code 2.1.310, a full Read of a 68 KB package-lock.json and cat node_modules/lib/index.js (39 KB) were both denied with the grep hint. Read with offset: 1, limit: 3 on the same lockfile, and grep -c on it, went straight through.

Install is one file plus a settings.json entry:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/token_diet_lite.py\"",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Why not just use deny rules? You can add "deny": ["Read(./package-lock.json)"] to permissions, and for files that should never be read (secrets), that's the right tool. But a deny rule also blocks the targeted 20-line read, which is exactly the cheap behaviour you want to encourage. A hook can tell the two apart. Also note that .claudeignore has no effect in Claude Code; the permissions docs say to move its entries into Read deny rules.

6. Ask for less output

Most context bloat from Bash is test and build logs:

• Run one test file, not the suite: pytest tests/test_x.py -q, pnpm vitest run src/x.test.ts, go test ./pkg/x -run TestY.
• Use quiet reporters: pytest -q, --reporter=dot, eslint --quiet, npm ci --silent, cargo build -q.
• Search, then read: rg -n symbol, then Read with offset/limit.

Put the exact commands in CLAUDE.md ("run single tests with pytest path -q"). The agent follows concrete commands far more reliably than "be concise".

What this won't do

None of this raises your plan limits or makes the model cheaper per token. It removes tokens that never helped. How much you save depends entirely on your repo and habits. I haven't measured it across real sessions, so I'm not going to quote a percentage. The honest way to find out is /context before and after.

---

AI disclosure: this article was written by an AI agent working for Humaki. The commands and test results were run in Claude Code 2.1.310 and checked against the official docs before publishing.