Cut Claude Token Usage

Tokens (small chunks of text that Claude reads and writes) are the new cloud bill. On the API, waste shows up on your invoice. On a subscription, it is a usage limit you hit before lunch. This guide covers both, plus CLAUDE.md, handoff files and sessions.

• API or Console billing (pay per token): every input, output and cache token is invoiced. Fewer tokens, less money.
• Subscription (Pro, Max, Team or Enterprise seats): a flat fee with rolling usage limits. Claude Code’s docs note the session cost figure is not relevant for billing on Pro and Max. Saving tokens buys more work, not a smaller bill.

For scale, the same docs put the enterprise average at about 13 dollars per developer per active day, or 150 to 250 dollars per developer per month. Check Anthropic’s pricing page before you budget.

1. Prompt caching (reusing a prompt’s unchanged start at a lower price). Put stable content first (tools, system prompt, documents), variable content last. On most models a 5-minute cache write costs 1.25x the base input price and a read 0.1x. The newest models charge even less for reads. Very short prompts aren’t cacheable, so check your model’s minimum.
2. Model routing. Smallest model for classification and extraction, mid-tier for everyday coding, top tier only for the hardest reasoning. Prices differ by an order of magnitude, so this is usually the biggest lever. See the model overview for current options.
3. Batch API. Work that can wait up to 24 hours costs 50% less on input and output, and stacks with caching.
4. Context editing and compaction. Context editing clears old tool results past a threshold, 100,000 input tokens by default. Server-side compaction summarizes long conversations.
5. Tool hygiene. Cache tool definitions from day one. Add tool search at roughly 20 tools or more.
6. Watch the tokenizer. Anthropic’s pricing page says newer models’ tokenizer produces roughly 30% more tokens for the same text. Re-baseline cost estimates after you migrate.

Claude Code already applies prompt caching and auto-compaction. What stretches your limits is behavior:

• /usage shows what consumes your plan, by skill, subagent, plugin and MCP server.
• /clear between unrelated tasks. A fresh start costs nothing.
• Keep CLAUDE.md short. Remove unused MCP servers (connections to outside tools).
• Install a behavioral plugin such as Ponytail.

What Ponytail is

Ponytail is an open-source (MIT) plugin and skill by Dietrich Gebert, on GitHub as DietrichGebert/ponytail and on npm as @dietrichgebert/ponytail.

It makes the agent think like a lazy senior developer. Before writing code, it asks:

• Does this need to exist?
• Is it already in the codebase?
• Does the standard library or platform do it?
• Can it be one line?

Validation, error handling, security and accessibility are explicitly kept. Less code written means less code read back later.

Install (Claude Code)

Run these as two separate prompts:

/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail

Switch intensity with /ponytail plus lite, full, ultra or off. Other commands: /ponytail-review, /ponytail-audit, /ponytail-debt and /ponytail-gain.

Advertised versus measured

The author advertises cost cuts of roughly 20 to 26 percent.

JetBrains’ independent test (July 2026, 80 paired tasks) measured a median cost cut of 10.3 percent, about 15 percent less code and about 11 percent less time, with no detectable quality difference.

A real saving, but about half the advertised one. The test was data and analysis heavy, so results depend on how much your agent over-builds.

Does it fit API or subscription use?

Both. On the API, 10 percent comes off your invoice. On a subscription, it stretches your limits.

Caveats

• Install it as a plugin, not a bare skill file. In JetBrains’ tests, a skill in a skills folder never activated by itself. The plugin’s session hook loads the rules.
• Savings concentrate where agents over-build. Lean tasks barely move.
• Install only from the official GitHub repo or npm package, using commands from the official README. At least one third-party guide lists a different repo owner.

Comparison

Be wary of vendor-run benchmarks. A tool’s own author wrote at least one popular comparison.

A CLAUDE.md file holds instructions Claude reads at the start of every session, as context, not enforced settings. For a guaranteed rule, use a hook (a script Claude Code runs automatically).

Where it lives

What to include, and what to leave out

• Include: build and test commands, conventions, project layout, always-do-X rules, mistakes Claude made twice.
• Leave out: multi-step procedures (make them skills), area-specific rules (use path-scoped rules), stale or contradictory content, secrets.
• Size: under 200 lines per file. At-sign imports help organization but don’t reduce context cost.
• Tools: /init generates a starter file. /context shows what loaded.

Starter template

# Project: your-project-name
<!-- Maintainer note: keep under 200 lines -->

## Stack
- Next.js, TypeScript strict, Tailwind, Postgres via Prisma

## Commands
- Install: pnpm i
- Dev: pnpm dev
- Test one file: pnpm vitest run path/to/file
- Before committing: pnpm lint && pnpm typecheck

## Layout
- API handlers: src/api/handlers/
- UI components: src/components/ui/ (reuse before creating new)

## Conventions
- 2-space indentation, named exports only
- Never hardcode colors, use tokens in src/styles/tokens.ts

## Workflow
- For changes touching more than 3 files, plan first, then implement
- Run the relevant tests after every change

## Compaction
- When compacting, always keep: modified files, failing tests, open TODOs, key decisions

Two built-in mechanisms exist, but a plain file you control beats both for carrying context between sessions.

• Claude Code auto memory: notes Claude writes in a per-project memory folder, indexed by MEMORY.md. Each session loads the first 200 lines. Open it with /memory.
• API memory tool: client-side. Claude issues file commands against a memories directory; your code implements storage. Pair it with context editing so memory calls are never cleared.
• Handoff file: before clearing or stopping, ask “Update HANDOFF.md using the template. Be terse.” Next session: “Read HANDOFF.md and continue from Next steps.”

HANDOFF.md template

# Handoff - feature or branch - date and time

## Goal
One sentence: what done looks like.

## Current state
- Branch and commit
- Works: ...
- Broken or failing: the exact command and the failing tests

## Decisions and why
- Chose A over B because ...

## Files touched
- path (what changed)

## Next steps (ordered)
1. ...
2. ...

## Gotchas, do not retry
- Tried X, fails because ...

## Open questions for the human
- ...

Context is everything Claude holds in a session: messages, files read, tool results. These built-in commands keep it lean.

Also: write specific prompts that name files, because vague prompts force exploration and exploration costs context. And keep only the MCP servers you use.

1. Know whether you are on the API or a subscription.
2. Keep CLAUDE.md under 200 lines.
3. Install Ponytail as a plugin.
4. Use plan mode for anything touching more than three files.
5. Send research to subagents.
6. Compact at milestones and clear between tasks.
7. Update HANDOFF.md before you stop.
8. API only: cache, route and batch.