---
name: token-efficiency
description: "Token economy rules: diff-over-rewrite, context compression, avoid verbose re-explanations, minimize round-trips."
---

# Token Efficiency

Practices to minimise token waste across all sessions.

## Context Management

- Do not re-send large context blocks. Reference existing files by path instead.
- Use /compact when context window grows large.
- Load only relevant file sections, not entire large files.
- One task per session where practical. Flush context between unrelated tasks.

## Output Format

- Return diffs, not full file rewrites.
- Keep explanations concise — bullets over paragraphs.
- Do not repeat information the user already knows.
- Do not generate boilerplate unless asked.

## File References

- When prior context is needed, read doc_internal/CONTEXT.md (if it exists in the project) rather than re-generating from scratch.
- For architecture context, reference doc_internal/ARCHITECTURE.md rather than re-explaining the system.

## Task Budgets (Opus 4.7, public beta — API only)

An advisory token budget for the **full agentic loop**, not a single request. Currently public beta on Opus 4.7 via the API; not available in Claude Code or Cowork at launch.

- Set via `output_config.task_budget: {type: "tokens", total: N}` in the API request.
- Minimum `total`: **20,000 tokens**.
- The model sees a running countdown of the budget and self-regulates: prioritizes higher-value work first, finishes gracefully as the budget approaches zero rather than getting cut off mid-thought.
- **Advisory, not enforced.** `max_tokens` is still the hard cap per individual request. `task_budget` shapes behavior across the loop; it does not stop a request from completing.

How it composes with `effort`:

- `effort` controls **depth per step** (how hard Claude thinks about each turn).
- `task_budget` controls **breadth across the loop** (how much total work Claude attempts before wrapping up).
- Use both together for long agentic runs where you care about end-to-end token cost.

## `/btw` — Side Questions Without Polluting Context

Opus 4.7 introduces `/btw <question>` for quick sidebar questions that **never enter conversation history**.

- The answer appears in a dismissible overlay.
- Conversation context, cache breakpoints, and the running task remain untouched.

**Important — `/btw` has no tool access.** It cannot read files, run bash, search the codebase, or call MCP tools. It can only answer from what is **already in the current conversation context** (files Claude has already read, prior tool output, system prompts, loaded memory). If the information you need isn't already in context, `/btw` cannot fetch it.

**Good `/btw` questions** (answerable from existing context):

- "What did that error message say again?"
- "What was the function signature we discussed earlier?"
- "Remind me what option we picked for the auth flow?"
- "Summarize what's in the file you just read."

**Not good for `/btw`** (require tools, ask as a normal turn instead):

- "Which file is `Foo` defined in?" — needs grep.
- "What's the latest version of package X?" — needs network.
- "Read file Y and tell me…" — needs Read.

If the answer requires fresh tool work, ask it as a normal turn so the lookup runs and the result becomes part of the conversation record.

## Prompt Caching Discipline

Per Anthropic's April 30 2026 guidance, prompt caching is the single most important token optimization for Claude Code workflows. Specific rules to keep cache hit rates high:

- **Don't switch thinking modes mid-session.** Toggling between `adaptive` and `enabled`/`disabled` breaks per-message cache breakpoints. Pick one and stay with it. (See `opus-4-7-features.md` § Caching Awareness.)
- **Use `ENABLE_PROMPT_CACHING_1H=1` for sessions over 30 minutes.** Default 5-minute TTL evicts warm cache between turns when you take a break. (See `opus-4-7-features.md` § Prompt Caching.)
- **Use `/clear` between unrelated tasks.** Stale context wastes cache and degrades performance — the cache stays warm only for context that's actually still being used.
- **Reference files by path, don't paste their contents back in.** Re-pasted content has no cache history; a path reference re-uses the prior read's cache entry.
