finance
Token Economics Cheat-Sheet: Claude Code Cost Controls Reference
Token Economics Series: Part 1: Your AI Bill Is Lying to You | Part 2: The Practitioner’s Toolkit | Part 3: Scaling the Discipline | Cheat-Sheet
This is the quick-reference companion to the Token Economics series. No narrative, no opinions — just every command, setting, and mechanism you need for tracking and controlling Claude Code token spend, organised by task and by feature. The examples are Claude Code specific, but the underlying principles — model selection, effort control, context discipline, visibility — transfer to any AI coding tool. Keep this open while you work.
Quick Reference: “How Do I…”
| Goal | Answer |
|---|---|
| Switch model mid-conversation? | /model sonnet |
| Switch model per subagent? | model: haiku in subagent frontmatter |
| Cap spending on a single run? | --max-budget-usd 5.00 (print mode only) |
| See cost right now? | /cost (API) or /context (all) or status line |
| See cost always? | Status line with ccusage or custom script |
| Reduce thinking cost? | /effort low or MAX_THINKING_TOKENS=0 |
| Stop background token usage? | DISABLE_NON_ESSENTIAL_MODEL_CALLS=1 |
| Get team-wide usage data? | Admin API: Usage Report + Cost Report endpoints |
| Keep logs forever? | "logRetentionDays": 100000 in settings.json |
| Analyse my own logs? | npx ccusage daily or DuckDB on JSONL |
| Limit MCP overhead? | /mcp to disable unused servers, MAX_MCP_OUTPUT_TOKENS |
| Use cheapest model? | --model haiku or model: haiku in subagent |
| Prevent reading huge files? | PreToolUse hook on Read tool |
| Get fastest responses? | /fast (Opus only, $30/$150 MTok) |
Model Selection & Switching
| Method | Scope | Persists? | Details |
|---|---|---|---|
/model | Mid-session | Until session ends | Interactive picker with effort slider |
/model sonnet | Mid-session | Same session | Shorthand, skips picker |
--model <name> | Session start | That session | CLI flag |
ANTHROPIC_MODEL env var | All sessions | Until unset | Environment variable override |
model in settings.json | Default | Yes | Via /config or direct edit |
model: frontmatter | Per-skill/subagent | N/A | Each can run different model |
opusplan alias | Configurable | Configurable | Opus for planning, Sonnet for execution |
--fallback-model | Print mode | That invocation | Auto-fallback when overloaded |
Available aliases: opus, sonnet, haiku, opusplan. Append [1m] for 1M context: opus[1m], sonnet[1m].
Enterprise restriction: availableModels in managed/policy settings restricts which models users can select.
Auto-fallback: Claude Code may automatically fall back from Opus to Sonnet if you hit a usage threshold.
Effort & Thinking Controls
Effort Levels
| Level | Behaviour |
|---|---|
| low | Fast, cheap, minimal thinking. Good for straightforward edits. |
| medium | Default for Opus 4.6 and Sonnet 4.6. Recommended for most coding. |
| high | Deeper reasoning, more thinking tokens. For hard debugging, architecture. |
| max | Opus 4.6 only. No constraint on thinking token spend. Does not persist across sessions. |
Setting Effort
| Method | Scope | Details |
|---|---|---|
/effort | Mid-session | Slash command. Shows what auto currently resolves to. |
/effort auto | Mid-session | Reset to default adaptive behaviour |
Effort slider in /model | Mid-session | Left/right arrows adjust |
--effort <level> | Session start | CLI flag. Does not persist. |
CLAUDE_CODE_EFFORT_LEVEL | All sessions | Highest precedence. Overrides all other methods. |
effortLevel in settings.json | Default | Persists across sessions. |
effort: frontmatter | Per-skill/subagent | Overrides session level. Does not override env var. |
Thinking Token Controls
| Setting | Effect |
|---|---|
MAX_THINKING_TOKENS=N | Override fixed thinking budget. For Opus/Sonnet 4.6, only applies when set to 0 or with CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1. |
MAX_THINKING_TOKENS=0 | Disable thinking entirely |
Option+T / Alt+T | Quick toggle thinking on/off |
Ctrl+O (verbose mode) | Makes thinking visible — see what it’s spending on |
CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 | Revert to fixed thinking budget controlled by MAX_THINKING_TOKENS |
Context & Session Management
Commands
| Command | What it does |
|---|---|
/context | Live breakdown by category (files, tools, MCP, history, system) with optimisation suggestions |
/compact [focus] | Compress history. Optional focus: /compact Focus on API usage |
/clear | Full context reset. Wipes conversation history. |
/rename <name> | Name session before clearing so you can find it later |
/resume | Resume previous session by ID or name |
--continue / -c | Continue most recent conversation in current directory |
--fork-session | Branch from a resumed session without affecting the original |
/rewind | Restore conversation and code to a previous checkpoint |
Esc+Esc | Open rewind/checkpoint UI |
Esc+Esc then “Summarize from here” | Compact only from a selected point forward |
Shift+Tab x2 | Enter plan mode — Claude plans before executing, preventing costly rework |
Escape | Stop current generation immediately |
Auto-Compaction
Auto-compaction triggers when approaching context limits. It summarises the conversation while preserving code patterns, file states, and key decisions. Custom compaction instructions can be set in CLAUDE.md under # Compact instructions. Circuit breaker: stops after 3 consecutive failures.
Warning: Compaction itself consumes tokens. One developer found it consuming ~80% of session token usage silently. Monitor with /cost.
1M Context Window
Available for Opus 4.6 and Sonnet 4.6. Automatic on Max, Team, and Enterprise plans. Enable via /model opus[1m] or /model sonnet[1m]. Standard pricing — no premium for tokens beyond 200K. Disable with CLAUDE_CODE_DISABLE_1M_CONTEXT=1.
Cost & Usage Visibility
Built-in Commands
| Command | Who it’s for | What it shows |
|---|---|---|
/cost | API users (not relevant for Pro/Max billing) | Session cost ($), API duration, wall duration, lines added/removed |
/stats | Subscribers (Pro/Max) | Usage patterns over time |
/context | All users | Token breakdown by category, context window fill %, optimisation suggestions |
/usage | VS Code extension | Plan usage view |
Status Line
A customisable bar at the bottom of Claude Code that runs any shell script you configure, receiving JSON session data on stdin.
Configuration in settings.json:
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh",
"padding": 0
}
}Use /statusline and Claude Code will generate a status line script for you interactively.
Available data fields (JSON on stdin):
| Field | Description |
|---|---|
model.display_name | Current model name |
context_window.used_percentage | Context fill percentage |
context_window.total_tokens | Total context window size |
current_usage.input_tokens | Cumulative input tokens this session |
current_usage.output_tokens | Cumulative output tokens this session |
current_usage.cache_creation_input_tokens | Cache creation tokens |
current_usage.cache_read_input_tokens | Cache read tokens |
current_usage.total_cost_usd | Session cost in USD |
rate_limits.5h.used_percentage | 5-hour window usage (subscribers) |
rate_limits.7d.used_percentage | 7-day window usage (subscribers) |
Note: current_usage is null before the first API call. rate_limits was added in v2.1.80.
JSONL Logs
| Aspect | Detail |
|---|---|
| Location | ~/.claude/projects/<encoded-directory>/*.jsonl |
| Format | One JSON object per line per event |
| Content | User messages, assistant messages (with usage object), tool calls, results, metadata |
| Retention | Default: 30 days, then deleted. Override: "logRetentionDays": 100000 in settings.json |
| Per-message fields | input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens |
| Session metadata | sessionId, parentUuid, uuid, timestamp, cwd, gitBranch, version |
| Querying | DuckDB: SELECT * FROM read_json_auto('session.jsonl') |
Third-Party Analysis Tools
| Tool | Install | What it does |
|---|---|---|
| ccusage | npx ccusage daily | Daily/monthly/session/5-hr block reports, model breakdown, statusline integration, MCP server mode |
| Claude-Code-Usage-Monitor | pip install claude-code-usage-monitor | Real-time terminal dashboard, burn rate predictions, plan limit detection, P90 analysis |
| claudetop | GitHub | Status line with live cost, cache efficiency, plugin system (8 extensions) |
| claude-code-log | uv run claude-code-log | JSONL to HTML/Markdown conversion for readable audit trails |
| clog | GitHub | Web-based viewer with real-time file watching, conversation threading, token display |
Caching
Prompt caching is automatic — no configuration needed. But understanding it is critical for cost control.
How It Works
Repeated content (system prompts, CLAUDE.md, conversation history) is cached server-side. Subsequent messages only pay the cache read price. Cache is invalidated by changing CLAUDE.md, system prompts, or anything in the prefix — keep them stable.
TTL
- Default: 5 minutes. Pause longer than 5 minutes and you pay full uncached input price on resume.
- Extended: 1 hour available. Cache write tokens cost 2x base input price. Cache reads cost 0.1x base price.
Pricing (Sonnet 4.6)
| Token type | Price |
|---|---|
| Standard input | $3/MTok |
| Cache read | $0.30/MTok (90% savings) |
| Cache creation | $3.75/MTok (25% premium) |
200K Token Price Break
| Condition | Sonnet 4.6 Input | Sonnet 4.6 Output |
|---|---|---|
| Input up to 200K tokens | $3/MTok | $15/MTok |
| Input over 200K tokens | $6/MTok | $22.50/MTok |
This applies per-request. Keep individual requests under 200K input tokens where possible.
CLI Flags & Environment Variables
Cost-Relevant CLI Flags
| Flag | Effect |
|---|---|
--max-budget-usd <N> | Hard spending cap (print mode only) |
--max-turns <N> | Limit agentic turns (print mode only) |
--bare | Minimal mode: skip hooks, skills, plugins, MCP, CLAUDE.md |
--model <name> | Set model for session |
--effort <level> | Set effort for session |
--fallback-model | Auto-fallback when primary model overloaded (print mode) |
--no-session-persistence | Don’t save session to disk (print mode) |
--disallowedTools | Remove specific tools from context entirely |
Cost-Relevant Environment Variables
| Variable | Effect |
|---|---|
ANTHROPIC_MODEL | Override model for all sessions |
CLAUDE_CODE_EFFORT_LEVEL | Override effort (highest precedence) |
MAX_THINKING_TOKENS | Cap or disable thinking tokens |
CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING | Revert to fixed thinking budget |
CLAUDE_CODE_DISABLE_1M_CONTEXT | Remove 1M context option |
MAX_MCP_OUTPUT_TOKENS | Cap MCP response size |
DISABLE_NON_ESSENTIAL_MODEL_CALLS | Suppress background model calls |
DISABLE_COST_WARNINGS | Suppress cost warning messages |
Hooks for Cost Control
Hooks give you 12 lifecycle events and 4 handler types (command, prompt, agent, HTTP) to intercept Claude Code’s behaviour. These are the cost-relevant patterns.
| Hook Event | Cost Lever | Example |
|---|---|---|
| PreToolUse (Bash) | Filter data before Claude reads it | grep for ERROR instead of cat-ing 10K lines |
| PreToolUse (Read) | Block reading large files | Deny reads >1000 lines, suggest subagent |
| PreToolUse (WebFetch/WebSearch) | Warn before expensive ops | Remind user that web tools consume extra tokens |
| PostToolUse (Write/Edit) | Auto-format to prevent rework | npx prettier --write on every file write |
| PostToolUse (Write) | Cheap security review | Haiku prompt hook auditing writes |
| Stop | Force continued work | Block premature stopping |
| PreCompact | Customise compaction | Control what gets preserved during auto-compaction |
| SessionStart | Load context efficiently | Inject relevant context once |
Skills & Subagent Cost Patterns
Skills
| Feature | Cost Impact |
|---|---|
| On-demand loading | Skills load only when invoked. Full content stays out of context until needed. |
disable-model-invocation: true | Keeps even the skill description out of context until manually invoked |
| Move instructions to skills | CLAUDE.md loads at session start. Skills load on demand. Target: CLAUDE.md under 200 lines. |
model: frontmatter | Run a skill on a cheaper model |
effort: frontmatter | Override effort level per-skill |
Subagents
| Feature | Cost Impact |
|---|---|
| Separate context window | Subagent’s verbose reads/output don’t bloat your main conversation. Only a summary returns. |
model: haiku | Run subagent on cheapest model |
effort: frontmatter | Control reasoning depth per-subagent |
| Built-in subagents | Explore (read-only, code search), Plan (architecture reasoning) |
| Isolation | Each subagent gets fresh context. Their file reads don’t count against your main session. |
Agent Teams
Multiple simultaneous Claude instances. Token usage roughly proportional to team size — expect ~7x usage compared to standard sessions when teammates run in plan mode. Use Sonnet for teammates, not Opus. Clean up when done: active teammates consume tokens even if idle. Enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
Team & Org Controls
Admin APIs
| API | Endpoint | Key Capabilities |
|---|---|---|
| Usage Report | GET /v1/organizations/usage_report/messages | Bucket by 1m/1h/1d. Group by model, workspace, API key, service tier. Filter by model, workspace, date range. |
| Cost Report | GET /v1/organizations/cost_report | USD costs. Group by workspace or description. Parsed model and geo fields. |
| Claude Code Analytics | Separate endpoint | Workspace telemetry for Claude Code specifically |
Console Dashboard
Visual cost and usage reporting. Workspace spend limits configurable by admins. Available to Developer, Billing, and Admin roles.
Observability Integrations
| Platform | Mechanism |
|---|---|
| Datadog | Native integration tile. Pre-built dashboards. FOCUS-compliant cost attribution. |
| Honeycomb | Custom OpenTelemetry collector. Minute-level granularity. |
| LiteLLM | Open-source Python proxy. Virtual keys for per-developer tracking. PostgreSQL-backed budgets. |
| Bifrost | Compiled LLM gateway. Prometheus metrics. Hierarchical budget controls. |
For detailed coverage of observability platforms, see Part 3: Scaling the Discipline.
Version & Background Usage Notes
Version Pinning
Recent versions have had cache-breaking bugs that inflated costs 10-20x. Pin your version when stable. Check with claude --version, update with claude update.
Background Token Usage
Even when idle, Claude Code uses tokens for conversation summarisation (under $0.04/session) and command processing. Suppress non-essential background calls with DISABLE_NON_ESSENTIAL_MODEL_CALLS=1.
MCP Tool Overhead
MCP tool schemas are deferred by default — only tool names enter context until Claude actually uses a tool. Use /context to see what MCP tools are consuming, /mcp to disable unused servers, and MAX_MCP_OUTPUT_TOKENS to cap response size (default: 25,000 tokens, warning at 10K). Prefer CLI tools (gh, aws, gcloud) where possible — zero per-tool listing cost.
This reference is maintained by Viewyonder. For the strategic context behind these controls, read the Token Economics series. For help building token discipline into your team’s workflow, get in touch.