Model Selection & Cost Management

Claude Code connects to Anthropic's model family: Opus for the hardest reasoning, Sonnet as the default workhorse, and Haiku for fast, cheap tasks. Choose wrong and you're either paying Opus rates for something Haiku could handle or watching Sonnet struggle with a refactor that needed Opus's depth.

Cost management isn't about pinching pennies. It's about matching capability to task and setting caps so you never wake up to a surprise bill. Claude Code gives you model selection flags, reasoning effort controls, fallback chains, budget limits, and two dashboards , /cost and /context , that show exactly where your tokens are going.

What you'll learn

• --model sonnet|opus|haiku selects the model; Sonnet is the default and the right choice for most tasks
• --effort low|medium|high|max|auto controls how much compute the model spends on reasoning, higher effort = better results on hard problems, at higher cost
• --fallback-model haiku downgrades to a cheaper model when the primary model is unavailable; --max-budget-usd sets a hard cap per session
• /cost shows a per-model cost breakdown for the session; /context shows a grid of context usage by category

The problem

You start using Claude Code on everything, feature development, code review, debugging, CI pipelines. A month later you check your Anthropic bill and it's four times what you expected. Some of those tasks needed Opus. Most of them didn't. The problem isn't that you used Claude Code too much; it's that you used the same model for everything, and Sonnet on a one-line typo fix costs the same as Sonnet on a cross-module refactor.

The other side of the problem is capability. You ask Claude to untangle a circular dependency across six files and it produces a plausible-sounding change that doesn't actually work. The issue isn't your prompt, it's that Sonnet doesn't have the reasoning depth for that class of problem, and you didn't know there was a flag that would have given it to you.

Options & when to use each

Models

Model	Flag	Strengths	Cost profile	Use when
Sonnet	--model sonnet (default)	Strong coding, reliable tool use, fast	Medium	Daily development: writing features, reviewing PRs, debugging, refactoring single files
Opus	--model opus	Deepest reasoning, handles ambiguous specs, catches edge cases Sonnet misses	High (roughly 3-5x Sonnet)	Complex refactors across modules, architectural decisions, security audits, anything where a wrong answer is expensive
Haiku	--model haiku	Fastest, handles simple tasks well	Low (roughly 1/10 Sonnet)	Boilerplate generation, one-line fixes, linting, summarizing short diffs, tasks where speed matters more than depth

Reasoning effort

The --effort flag controls how much compute the model spends before answering. It applies to Opus and Sonnet, not Haiku:

Effort level	What it does	Cost impact	Use when
low	Minimal reasoning, fastest response	Cheapest	Simple questions, quick fixes, tasks where you'd use Haiku but want Sonnet's knowledge
medium	Moderate reasoning (default for most models)	Standard	Routine coding tasks
high	Extended reasoning	Higher	Hard bugs, non-trivial refactors, security-sensitive code
max	Maximum reasoning time	Highest	Architecture decisions, complex algorithms, anything where getting it right the first time saves more than the extra tokens cost
auto	Claude decides the effort level based on the task	Varies	Default, let Claude judge complexity. Switch to explicit effort when you know the task's difficulty

The tradeoff is real: --effort max on Opus can double the token cost of a single turn. But if that turn solves a bug that would have taken two hours of debugging, the cost is noise.

Budget and fallback controls

Flag	What it does	Example
--max-budget-usd	Hard cap on total API cost for this session. Claude stops when it reaches the limit	claude --max-budget-usd 5.00 stops at $5
--fallback-model	If the primary model returns an error (rate limit, outage), automatically retry with this model	claude --model opus --fallback-model sonnet downgrades to Sonnet if Opus is unavailable

The budget cap is a session-level guardrail, not a per-turn limit. If you set --max-budget-usd 10.00 and run a CI script that calls Claude 20 times, the cap applies to the entire session, all 20 calls share the $10 pool.

Build it

Step 1: Match model to task

Start a session explicitly:

# Routine feature work: default Sonnet
claude

# Hard refactor across multiple modules: Opus with high effort
claude --model opus --effort high

# Quick lint-and-fix loop in CI: Haiku
claude --model haiku -p "Fix lint errors in this file: $(cat src/broken.py)"

The pattern is: know the task's difficulty before choosing the model. If you're not sure, start with Sonnet. If it struggles, restart with Opus. If the task is trivial, switch to Haiku. The model flag is cheap to change but expensive to get wrong across hundreds of sessions.

Step 2: Set budget caps

For sessions where cost matters, CI pipelines, automated scripts, shared team usage:

# CI review: cap at $2 per run
claude --model sonnet --max-budget-usd 2.00 -p "Review this PR" --output-format json

# Batch processing: cap at $10 for the entire batch
claude --model haiku --max-budget-usd 10.00 -p "Summarize each function in src/" --output-format json

# Opus session: cap at $15 to prevent runaway costs on a hard problem
claude --model opus --effort high --max-budget-usd 15.00

If Claude hits the budget cap mid-session, it stops and reports the limit was reached. It doesn't silently truncate work or downgrade models.

Step 3: Configure fallback chains

In CI or automated environments where availability matters more than model quality:

# Production CI: Opus for review, fall back to Sonnet if Opus is down
claude --model opus --fallback-model sonnet -p "Review this diff" --output-format json

# Cost-sensitive automation: Sonnet by default, Haiku as fallback
claude --model sonnet --fallback-model haiku --max-budget-usd 5.00 -p "Process this batch"

Fallback happens transparently, Claude switches models and continues without restarting the session. The /cost command shows which model was actually used for each turn.

Step 4: Read the dashboards

During an interactive session, use two slash commands to understand where your tokens are going:

/cost

Shows a per-model cost breakdown for the current session: total tokens consumed, cost per model, and estimated session total. Check this periodically during long sessions to catch cost surprises before they compound.

/context

Shows a grid of context usage: how much of the context window is consumed by system prompts, conversation history, tool output, skills, and other categories. If skills or CLAUDE.md are eating disproportionate space, this is where you'll see it.

What goes wrong

Mistake	How you notice it	The fix
Using Opus for every task	Monthly bill is 5-10x higher than expected	Opus is for hard problems only. Audit your usage: if more than 20% of your sessions use Opus, you're probably overusing it. Set --model sonnet as the default and use Opus explicitly for complex tasks
Using Haiku for tasks it can't handle	Haiku produces code that looks right but has subtle logic errors	Haiku is fast and cheap but has limited reasoning depth. Reserve it for tasks with objective correctness criteria: lint fixes, boilerplate, formatting. Don't use it for logic, architecture, or security
--effort max on simple tasks	Response takes longer but isn't better	Effort controls reasoning compute, not output quality on simple tasks. A one-line fix doesn't benefit from max effort. Use auto and only escalate when Claude struggles
Budget cap too low for the task	Claude stops mid-task and reports the cap was hit	Estimate before capping: a typical Sonnet session costs $0.50-$3.00 depending on context size and turns. Opus sessions run $2-$15. Set caps 50% above your estimate to allow for retries
Fallback model too weak for the task	Primary model fails, fallback kicks in, output quality drops	If the task needs Opus, don't fall back to Haiku. Use --fallback-model sonnet for Opus sessions and --fallback-model haiku only for Sonnet sessions on non-critical tasks

Confirm it worked

Run the same task on three models and compare cost and quality:

# 1. Quick lint fix on Haiku
time claude --model haiku --max-budget-usd 1.00 -p "This Python file has lint errors. List them: $(cat /tmp/test-lint.py 2>/dev/null || echo 'x=1;y=2')" --output-format json 2>/dev/null

# 2. Same task on Sonnet
time claude --model sonnet --max-budget-usd 1.00 -p "This Python file has lint errors. List them: $(cat /tmp/test-lint.py 2>/dev/null || echo 'x=1;y=2')" --output-format json 2>/dev/null

# 3. Check cost dashboard in an interactive session
claude
> /cost
# Expected: shows per-model breakdown with costs
> /context
# Expected: shows context usage grid

In an interactive session, test model switching mid-session:

> /model opus
# Expected: Claude switches to Opus for the next turn
> Explain the architecture of this codebase at a high level
> /model sonnet
# Expected: Claude switches back to Sonnet

If /cost shows accurate per-model tracking, /context shows a usage breakdown, and you can switch models with the /model command, you have full control over capability and cost. You're ready to make model selection a deliberate choice rather than a default.

Next: Pipe, Script & Automate, running Claude Code headlessly in shell pipelines.