How to save tokens in Claude Code: /context, /compact, subagents and cache

Q: How do you see how many tokens Claude Code is using?

Use /context to see what is in the context right now, by category. Use /usage to see the session's tokens and estimated cost. Since version 2.1.251, /usage also shows the prompt cache hit rate.

Q: Which saves more: /compact or /clear?

/clear, which per the docs costs nothing. /compact sends a request with the whole conversation to write the summary. Use /clear when the next task is unrelated to the last one and /compact when you need to keep continuity.

To save tokens in Claude Code, keep the context small. Run /context to see what takes up space. Use /clear when you switch tasks and /compact with instructions at breaks between tasks. Send heavy reads, like tests and logs, to a subagent. Pick your model at the start of the session, because each model has its own prompt cache and switching midway reprocesses everything. And trim what loads before your first prompt: a long CLAUDE.md and MCP servers you do not use.

The rule is in the Claude Code costs docs: token costs scale with context size. Every message resends the whole conversation. The prompt cache makes the repeated part cheaper, but not free.

What I tested and what I did not. /context runs without a login in non-interactive mode (claude -p "/context"), so the context tables in this guide are real Claude Code 2.1.296 output. /compact, /usage and cache behavior need a logged-in session. For those, the source is the docs, and the output is labeled as an example. The concept side of context engineering is in harness, RAG and context engineering.

How do you see what is using tokens with /context?

Inside a session, run /context. It shows usage by category and suggests what to cut. Outside a session, claude -p "/context" prints the same table as markdown. This is the output in an empty folder, with no CLAUDE.md and no MCP:

$ claude -p "/context"
## Context Usage

**Model:** claude-opus-5-5
**Tokens:** 15.7k / 1m (2%)

### Estimated usage by category

| Category                | Tokens | Percentage |
|-------------------------|--------|------------|
| System prompt           | 1.9k   | 0.2%       |
| System tools            | 11.9k  | 1.2%       |
| System tools (deferred) | 15.1k  | 1.5%       |
| Skills                  | 2k     | 0.2%       |
| Free space              | 951.3k | 95.1%      |
| Autocompact buffer      | 33k    | 3.3%       |

Note that the (deferred) rows stay out of the total: System prompt, System tools and Skills add up to the 15.7k, give or take rounding. They are deferred tools, which only really load when Claude needs them. The numbers vary with version, model and configuration.

How much does a large CLAUDE.md cost?

CLAUDE.md enters the context at the start of every session. In the same folder I created a synthetic 302-line CLAUDE.md, one single-sentence rule per line, and ran it again:

$ wc -l CLAUDE.md
302 CLAUDE.md

$ claude -p "/context"
...
**Tokens:** 29.2k / 1m (3%)
...
| Memory files            | 12.3k  | 1.2%       |
...
### Memory Files

| Type    | Path                   | Tokens |
|---------|------------------------|--------|
| Project | /tmp/ctx-lab/CLAUDE.md | 12.3k  |

That is 12.3k extra tokens in every session, before you type anything. The docs recommend keeping CLAUDE.md under 200 lines and moving instructions for specific workflows, like PR reviews or database migrations, into skills, which load only when invoked. The how-to is in how to write a CLAUDE.md and how to create a Skill.

When should you use /clear, /compact or /rewind?

All three shrink the context, each in its own way:

Command	What it does	What it costs	When to use it
`/clear`	Starts a new conversation with an empty context. CLAUDE.md and project memory reload	Nothing, per the docs	When you switch to a task unrelated to the last one
`/compact [instructions]`	Summarizes the conversation and replaces the history with the summary	One request that reads the whole conversation to write the summary	At a break between tasks, when you want to keep continuity
`/rewind`	Takes the conversation back to an earlier turn	Reuses a prefix that is already cached	When you went down the wrong path and want to drop it

Before /clear, run /rename so you can find the session later with /resume. For /compact, say what to keep:

/compact Focus on the failing tests and the changes in auth.ts

Or keep the instruction in CLAUDE.md. This is the docs' example:

# Compact instructions

When you are using compact, please focus on test output and code changes

What survives /compact?

Per the context window page: the project-root CLAUDE.md and auto memory come back from disk. Up to five files Claude read or edited come back, most recently modified first. Rules with paths: and nested CLAUDE.md files only come back when Claude reads a file that triggers them again. If a rule must hold after compaction, put it in the project-root CLAUDE.md.

/compact is not free. To write the summary, Claude Code sends a request with the whole conversation. With a warm cache, that read is billed at the cache rate and costs a fraction of the context size. After a break longer than the cache lifetime, it is reprocessed from scratch. That is why the docs suggest compacting between tasks, instead of waiting for auto-compaction to kick in during one.

How does the prompt cache affect cost?

The model remembers nothing between requests, so Claude Code resends everything with every message. The cache matches the start of the request, the prefix, against what the API processed recently and bills that re-read at the cache rate. The match is exact: if something changes near the start, everything after it is reprocessed. The full explanation is on the prompt caching page.

What invalidates the cache, per the docs:

Switching models with /model. Each model has its own cache.
Changing the effort level, on most models.
Turning on fast mode.
Connecting or removing an MCP server when tools load upfront, without tool search.
/compact itself, by design.
Piling up images until Claude Code has to drop the oldest ones.
Upgrading Claude Code. The first session after an upgrade builds its cache from scratch.

What keeps the cache: editing repository files, changing permission mode, invoking skills and commands, using /rewind and spawning a subagent. Editing CLAUDE.md mid-session does not break the cache either, but the edit only applies after /clear, /compact or a restart.

How long does the cache last?

Request	Subscription, within plan usage	Usage credits, API key or cloud
Main conversation	1 hour	5 minutes
Subagents, compaction and the rest	5 minutes (some helpers get 1 hour)	5 minutes

Every request that hits the cache resets the clock. If you use an API key and take long breaks, you can ask for 1 hour on the main conversation with the promptCacheTtl setting or the CLAUDE_CODE_PROMPT_CACHE_TTL=1h variable (Claude Code 2.1.242 or later):

{
  "promptCacheTtl": "1h"
}

Writes to the 1-hour cache are billed at a higher rate. It only pays off if you really sit idle for more than five minutes between messages.

How do you check that the cache is working?

Run /usage. Since version 2.1.251, the Session block has a Prompt cache (main) line. This is the docs' example, not my output:

Prompt cache (main):   14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · 1 expected rebuild (compaction or tool-result clearing) · warm (1h TTL, last activity 40s ago)

Many misses in a row mean something in the prefix keeps changing. Since 2.1.260, the line tries to name the cause, for example likely cause: tool definitions changed.

Do subagents save tokens?

They save context in the main conversation, which is a different thing. The docs' tactic is to send output-heavy work to a subagent: running the test suite, fetching docs, processing logs. The verbose output stays in its context and only the summary comes back to you. The docs' example prompt:

Use a subagent to run the test suite and report only the failing tests with their error messages

But the subagent's requests also count toward your usage, and it does not read the main conversation's cache, because its prefix is different. To spend less, the docs suggest a smaller model for the subagent, like model: haiku in its config. Use it as a targeted tactic, for heavy reads.

What else cuts tokens in Claude Code?

Pick the model at the start. The docs say Sonnet handles most coding tasks and costs less than Opus. Switching mid-session resets the cache.
Lower the effort on simple tasks. Thinking tokens are billed as output. Use /effort or adjust it in /model.
Turn off the servers you do not use in /mcp, and prefer a CLI like gh or aws when one exists, because a CLI adds no tool listing. MCP setup is in how to configure MCP in Claude Code.
Filter output with hooks. A PreToolUse hook can swap npm test for a version that only shows failures. See how to configure hooks in Claude Code.
Be specific in your prompt. "Add input validation to the login function in auth.ts" makes Claude read fewer files than "improve this code".
Use plan mode (Shift+Tab) on complex tasks and press Esc as soon as Claude heads the wrong way.

One measurement on tool search, in a folder with four HTTP MCP servers configured. Turning tool search off almost doubled the starting context:

$ claude -p "/context"                          # tool search on (default)
**Tokens:** 20.3k / 1m (2%)

$ ENABLE_TOOL_SEARCH=false claude -p "/context"
**Tokens:** 39k / 1m (4%)
| System tools            | 28.3k  | 2.8%       |
| MCP tools               | 2.2k   | 0.2%       |

Most of the jump came from Claude Code's own built-in tools, which also stop being deferred. The MCP tools added up to 2.2k. Leave tool search at its default.

Why does usage climb in a long session?

The docs list the usual reasons:

Long context: every message carries the whole conversation, so a one-line question in a session that has been open all day pays for the whole conversation, even at the cache rate.
Cold cache: the first message after a break longer than the cache lifetime reprocesses everything.
Scheduled tasks, subagents and teammates: each one sends its own requests.
Compaction: /compact on a large context is itself a large request. If you want a fresh start, /clear costs nothing.

Frequently asked questions

How do you see how many tokens Claude Code is using?▼

Use /context to see what is in the context right now, by category. Use /usage to see the session's tokens and estimated cost. Since version 2.1.251, /usage also shows the prompt cache hit rate.

Which saves more: /compact or /clear?▼

/clear, which per the docs costs nothing. /compact sends a request with the whole conversation to write the summary. Use /clear when the next task is unrelated to the last one and /compact when you need to keep continuity.

Does switching models mid-session cost more tokens?▼

Yes. Each model has its own cache, so the first request after /model reprocesses the whole conversation with no cache hits. Pick your model and effort at the start of the session.

Do subagents use more or fewer tokens?▼

They keep verbose output out of the main conversation, but their requests also count toward your usage and do not reuse the main conversation's cache. They pay off for heavy reads, like tests and logs, ideally on a smaller model.