How to Use Claude Haiku 5.5 in Claude Code (and as Your Subagent Model)

To use Claude Haiku 5.5 in Claude Code, update to v2.1.293 or later with claude update. Then start a session with claude --model claude-haiku-5-5, or switch models inside a session with /model claude-haiku-5-5. For most coding workflows, use Haiku as a subagent: configure model: haiku in a subagent file and let Sonnet 5.5 or Opus 5.5 delegate searches, test runs, and summaries. With an API key, pricing is $0.10/$0.50 per million input/output tokens for prompts up to 100K tokens, and $0.50/$2.50 above that threshold.

Try Apidog today

This guide covers setup, the haiku alias behavior, effort levels, subagent configuration, the 100K pricing threshold, and when Sonnet or Opus should remain the lead model. For model details, see what Claude Haiku 5.5 is. If your code calls APIs, Apidog can store the test scenarios a Haiku subagent runs.

Claude Haiku 5.5 in Claude Code at a glance

Setting	Haiku 5.5
Minimum version	v2.1.293 (claude update)
Model ID	claude-haiku-5-5
haiku alias	Haiku 5.5 on the Anthropic API only
Context	1M native on every plan; no [1m] suffix
Auto-compaction	About 967K tokens by default
Default effort	medium (low through max)
Thinking	Always on; cannot be disabled
API price	$0.10/$0.50 up to 100K prompt tokens; $0.50/$2.50 over 100K
Plans	Pro, Max, Team, Enterprise, or an API key; not Free

Step 1: Update Claude Code

Haiku 5.5 requires Claude Code v2.1.293 or newer. The changelog describes it as “now the default Haiku model on the Anthropic API.”

claude update

Claude Code is not available on the Free plan. Free users can select Haiku 5.5 in the Claude.ai apps, but Claude Code requires Pro, Max, Team, Enterprise, or an Anthropic API key.

According to claude.com/pricing, Pro costs $17/month when billed annually or $20/month, while Max starts at $100/month.

Step 2: Select Haiku 5.5 as the main model

Start Claude Code with the full model ID:

claude --model claude-haiku-5-5

Inside an existing session, run:

/model claude-haiku-5-5

If your saved model setting is haiku, a session previously saved on Haiku 4.5 resumes on Haiku 5.5 when using the Anthropic API.

The haiku alias only means Haiku 5.5 on the Anthropic API

Provider	haiku resolves to
Anthropic API	Haiku 5.5
Claude Platform on AWS	Haiku 4.5
Amazon Bedrock	Haiku 4.5
Google Cloud’s Agent Platform	Haiku 4.5
Microsoft Foundry	Haiku 4.5

On cloud providers, /model haiku and model: haiku in a subagent file select Haiku 4.5.

To use Haiku 5.5, pin the provider-specific model identifier:

• Google Cloud and Claude Platform on AWS: claude-haiku-5-5
• Microsoft Foundry: your deployment name
• Amazon Bedrock: an inference profile ID such as us.anthropic.claude-haiku-5-5

You can also point the haiku alias to the desired model with ANTHROPIC_DEFAULT_HAIKU_MODEL, covered in Step 5.

Step 3: Pick an effort level

Haiku 5.5 is the first Haiku model with effort control:

• low
• medium
• high
• xhigh
• max

Claude Code defaults to medium.

claude --model claude-haiku-5-5 --effort high

Inside a session, set an effort level with:

/effort low

That setting is saved for the current model.

Use the levels pragmatically:

• Use low for short tool calls, codebase searches, and high-volume tasks.
• Use medium for most development work.
• Use high for longer agent tasks.
• Use xhigh and max only when your evaluations show a measurable benefit.

Thinking is always enabled for Haiku 5.5 in Claude Code. Neither alwaysThinkingEnabled: false nor MAX_THINKING_TOKENS=0 disables it. The raw Messages API can disable thinking at high effort or lower, but Claude Code cannot. To reduce thinking tokens in Claude Code, lower the effort level.

Step 4: Run Haiku 5.5 as a subagent

Anthropic says Haiku 5.5 “pairs well with Opus 5.5 and Sonnet 5.5 as a subagent on coding work.”

Subagents are Markdown files with YAML frontmatter:

• Project scope: .claude/agents/
• User scope: ~/.claude/agents/

Only name and description are required. The subagent docs support sonnet, opus, haiku, fable, a full model ID, or inherit in the model field.

For more on scopes and tools, see the Claude Code subagent guide.

Replace Explore with a cheaper explorer

The built-in Explore subagent runs on the main conversation model. If your session uses Opus 5.5, every Explore search also uses Opus.

Create a user or project subagent named Explore to override the built-in one and assign it a separate model:

---
name: Explore
description: Fast read-only codebase search. Use to find files, symbols and call sites without editing anything.
tools: Read, Grep, Glob
model: haiku
effort: low
---

You search the codebase and report what you find. Return file paths with line
numbers and a short summary of each match. Never edit files.

Save the file as:

.claude/agents/Explore.md

Use /tasks while it runs to confirm the selected model.

On a cloud provider, replace haiku with the full Haiku 5.5 model ID from Step 2.

Force every subagent onto Haiku

To force every subagent, including Explore, to use Haiku, add both variables to a settings file:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

CLAUDE_CODE_SUBAGENT_MODEL by itself only sets a default. A subagent’s own model field still takes priority, and the built-in Explore agent does not move.

Step 5: Point background work at Haiku 5.5

ANTHROPIC_DEFAULT_HAIKU_MODEL configures the model used for haiku and background functionality, including summarizing prior sessions for claude --resume.

The older ANTHROPIC_SMALL_FAST_MODEL variable is deprecated according to the environment variable reference. Replace it if it is still set in your shell profile.

On the Anthropic API, no configuration is necessary. On cloud providers, background tasks may default to Sonnet or the primary model. Once Haiku 5.5 is enabled for your account, pin it explicitly:

# Google Cloud's Agent Platform
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-5-5

# Amazon Bedrock (inference profile ID)
export ANTHROPIC_DEFAULT_HAIKU_MODEL=us.anthropic.claude-haiku-5-5

The 100K price step in long sessions

Haiku 5.5 pricing depends on prompt length. Claude Code sends the conversation as the prompt on every turn.

After a session exceeds 100K tokens of context, each request is billed at:

• Input: $0.50 per million tokens instead of $0.10
• Output: $2.50 per million tokens instead of $0.50

That is five times the short-prompt rate.

The documentation does not specify whether cached tokens count toward the threshold, so budget as though they do.

Auto-compaction does not prevent this by default. Haiku 5.5 compacts at roughly 967K tokens, leaving plenty of room to cross the 100K pricing threshold first.

If you pay per token, use these two practices:

1. Compact earlier. Run /autocompact 100k, the lowest context window Claude Code accepts, to compact near the threshold rather than near 1M tokens.
2. Move bulky work into subagents. Each subagent has its own context, so test logs, search results, and generated reports stay out of the lead conversation.

Even above 100K tokens, Haiku’s $0.50/$2.50 pricing is one quarter of Sonnet 5.5’s $2/$10 rate.

On paid plans, sessions consume usage limits rather than direct token billing. Anthropic has not published how Haiku 5.5 counts against those limits. The Haiku 5.5 pricing breakdown walks through the cost arithmetic.

Max and Team subscribers should also note that monthly API credits do not cover interactive Claude Code usage. Anthropic’s API credits documentation lists $100 for Max 5x, $200 for Max 20x, and up to $500 pooled for Team.

When Sonnet 5.5 or Opus 5.5 should remain the lead

Anthropic says Sonnet 5.5 and Opus 5.5 “remain better choices for complex agentic coding tasks.”

On Terminal-Bench 4.0, run by Anthropic in Claude Code at max effort, Haiku 5.5 scored 39.2% compared with Sonnet 5.5 at 70.6%.

Effort	Haiku 5.5	Sonnet 5.5
medium	20.3% at $0.68	28.8% at $0.68
high	24.8% at $1.04	43% at $1.46
max	39.2% at $2.64	70.6% at $10.44

At medium, both models cost about the same per attempt, but Sonnet scores higher. Haiku’s lower token price does not automatically make it the better lead model for difficult shell-heavy coding sessions.

Computer use shows a different tradeoff. On OSWorld 2.1:

• Haiku 5.5 at medium: 53.3% at $0.13 per attempt
• Sonnet 5.5 at low: 57.9% at $0.68 per attempt

See the full Haiku 5.5 benchmarks breakdown and the Sonnet 5.5 Claude Code guide.

A practical setup is:

• Lead model: Sonnet 5.5 or Opus 5.5
• Haiku 5.5 subagents: Explore, test runners, log readers, and documentation fetchers

Example: A Haiku subagent that runs Apidog tests

Test runs are verbose and repetitive, which makes them a good Haiku workload.

The Apidog CLI runs saved Apidog test scenarios from the terminal. A subagent can execute the relevant scenario and return a concise report without adding full test output to the lead model’s context.

---
name: api-test-runner
description: Runs the project's Apidog test scenarios with the Apidog CLI after an API endpoint changes, then reports pass and fail counts with the failing requests.
tools: Bash, Read
model: haiku
effort: low
---

Run the Apidog CLI test command documented in this repo's README for the
scenario that covers the changed endpoint. Report the pass and fail counts.
For each failure, give the request name, the expected result and the actual
result. Don't edit code. Don't retry a failed run more than once.

For CLI setup, authentication, and the run command, see Apidog CLI in Claude Code. Download Apidog to create the scenarios the subagent runs.

Migrating an app from Haiku 4.5

If your app calls Haiku 4.5 through the API, start the migration from Claude Code:

/claude-api migrate this project to claude-haiku-5-5

Expect breaking changes. Haiku 5.5 returns a 400 error for:

• Manual budget_tokens thinking
• Non-default temperature
• Non-default top_p
• Any top_k
• Assistant prefill

The Haiku 5.5 vs. Haiku 4.5 guide lists each required fix.

After updating your code:

1. Save the old and new API requests as a pair in Apidog.
2. Store ANTHROPIC_API_KEY as an environment variable.
3. Assert on stop_reason and usage.
4. Fail tests when a new refusal stop reason appears or token usage jumps unexpectedly.

That turns model behavior changes into test failures instead of production issues.

FAQ

Is Haiku 5.5 the default model in Claude Code?

No. It is the default Haiku model on the Anthropic API, so the haiku alias points to it there. Select it as the main model with --model or /model.

Can I use Haiku 5.5 in Claude Code on the Free plan?

No. Claude Code requires a paid plan or an API key. Free users can choose Haiku 5.5 in the Claude.ai apps. See how to use Claude Haiku 5.5 for free.

Why does model: haiku give me Haiku 4.5?

You are using Bedrock, Google Cloud, Foundry, Claude Platform on AWS, or a Claude Code version older than v2.1.293. Pin the full model ID or configure ANTHROPIC_DEFAULT_HAIKU_MODEL.

Can I turn off thinking to save tokens?

Not in Claude Code. Lower the effort level instead; low is the cheapest setting.

Your next step

Run:

claude update

Then add the Haiku-powered Explore override and keep your current lead model for a week. If your project has APIs, add the test-runner subagent next.

To call the model from your own code, start with the Haiku 5.5 API guide. Apidog is free to start and provides real API scenarios for the subagent to run.