Understanding Claude Code Model Aliases: haiku, sonnet, opus, and inherit

Claude Code model aliases are shorthand identifiers that map to specific Anthropic models, allowing you to control speed, cost, and reasoning depth across sub-agents, commands, and global settings.

The shanraisshan/claude-code-best-practice repository documents how these four aliases—haiku, sonnet, opus, and inherit—provide a consistent interface for selecting underlying LLM capabilities without hard-coding full model identifiers like claude-3-haiku-20240307.

What Are Model Aliases?

A model alias is a human-readable token that the Claude Code CLI expands to a full Anthropic model ID. According to the source code analysis in best-practice/claude-settings.md, aliases offer forward-compatibility: if Anthropic renames a model, the alias remains stable while the underlying mapping updates. This abstraction layer lets you write configuration files that are readable today and resilient to model versioning changes tomorrow.

Aliases control three primary dimensions: latency (response speed), context window (token limit), and reasoning depth (capability for complex tasks). The repository explicitly documents these characteristics for each alias in the settings reference.

The Four Model Aliases Explained

haiku

The haiku alias maps to Claude 3 Haiku, optimized for lowest cost and fastest response times (approximately 100ms-scale latency). It features a 100K-token context window and excels at quick-turnaround tasks where deep reasoning is unnecessary.

Use haiku for file-system queries, simple code searches, and one-line edits. In .claude/commands/weather-orchestrator.md, the repository demonstrates hard-coding model: haiku for lightweight orchestration tasks that prioritize speed over sophistication.

sonnet

The sonnet alias targets Claude 3 Sonnet, representing the default sweet spot for general development work. With a 200K-token window and mid-tier pricing, it balances reasoning depth with moderate latency.

This alias handles multi-step refactors, class generation, and documentation tasks that require context awareness without the premium cost of the largest model. The repository recommends starting with sonnet when uncertain about task complexity.

opus

The opus alias invokes Claude 3 Opus, the high-depth, high-cost option for demanding workloads. Featuring a 200K-token window but slower response times (approximately 300ms-scale), Opus is reserved for heavy-weight reasoning.

Deploy opus for full-project architecture redesigns, long-form technical writing exceeding 2,000 tokens, or deep troubleshooting requiring multiple reasoning hops. The repository notes this alias triggers only when tasks repeatedly hit reasoning limits with smaller models.

inherit

The inherit alias is a contextual passthrough that applies no explicit model override. When specified in sub-agents or commands, the tool uses whatever model the parent session or global settings.json defines.

This alias ensures consistency across workflow steps. As documented in best-practice/claude-subagents.md, setting model: inherit in agent front-matter allows sub-agents to automatically align with user-selected session models, preventing model fragmentation in complex pipelines.

Where to Configure Model Aliases in Claude Code

Sub-agent Front-matter

Sub-agents defined in the repository use YAML front-matter to declare their default model. The file best-practice/claude-subagents.md specifies that the model field accepts any of the four aliases. When omitted, sub-agents typically default to the session model, but explicit aliases override this for specialized tasks.

# From best-practice/claude-subagents.md

name: explore-code
description: Fast read-only code exploration
model: inherit          # follows whatever model the user selected

tools: Read, Grep

Global Settings

The settings.json file exposes a top-level model key that understands these aliases. According to best-practice/claude-settings.md, this setting establishes the baseline for all Claude Code interactions in the project, which sub-agents can then override or inherit via the inherit alias.

{
  "model": "sonnet"
}

Individual Commands

Commands stored in .claude/commands/ can hard-code specific aliases to ensure consistent behavior regardless of global settings. The repository provides a concrete example in .claude/commands/weather-orchestrator.md, where model: haiku guarantees fast execution for weather data retrieval steps.

# From .claude/commands/weather-orchestrator.md

model: haiku
description: Fetch weather data quickly
steps:
  - fetch-current-conditions

When to Use Each Alias

Selecting the appropriate alias depends on balancing cost, speed, and cognitive load:

• Choose haiku for speed-critical operations: grep searches, file reads, and simple string replacements where latency matters more than nuance.
• Choose sonnet for the majority of development tasks: writing functions, refactoring modules, and generating standard documentation.
• Choose opus for high-stakes architectural work: complex planning, deep debugging sessions, and generating comprehensive design documents requiring extensive context analysis.
• Choose inherit for composable workflows: when building sub-agents or commands that should remain model-agnostic and respect the user's current session selection.

The repository emphasizes that you can switch models dynamically during a session using the /model slash command, allowing real-time optimization as task complexity shifts.

# Switching models on the fly in a session

/model haiku          # quick look-ups

/model opus           # deep design work

Summary

• Model aliases (haiku, sonnet, opus, inherit) abstract full Anthropic model IDs into readable, forward-compatible tokens.
• haiku delivers the fastest, cheapest responses for simple queries and edits, mapped in best-practice/claude-settings.md as the low-cost option.
• sonnet provides the balanced default for general development with a 200K-token window.
• opus offers maximum reasoning depth for complex tasks at higher latency and cost.
• inherit passes through the parent context's model selection, documented in CLAUDE.md and best-practice/claude-subagents.md for maintaining workflow consistency.
• Configuration occurs in three layers: global settings.json, sub-agent front-matter, and individual command headers.

Frequently Asked Questions

How do I switch between model aliases during an active Claude Code session?

Use the /model slash command followed by the desired alias. For example, typing /model haiku switches the session to the fastest model for quick lookups, while /model opus activates the deepest reasoning mode for complex architectural tasks. This runtime override affects subsequent interactions until you switch again or exit the session.

What happens if I specify model: inherit in a sub-agent but no parent model is set?

When using the inherit alias, the sub-agent falls back to the global default defined in settings.json. If no global default exists, Claude Code uses its built-in system default (typically sonnet). The repository's best-practice/claude-subagents.md explicitly recommends inherit for ensuring sub-agents align with user preferences without hard-coding assumptions.

Is there a performance difference between using an alias and the full model ID?

No measurable performance difference exists at runtime; the CLI expands aliases to full IDs before API calls. The primary benefit is maintainability: aliases future-proof your configuration against Anthropic model versioning changes. As noted in best-practice/claude-settings.md, if Anthropic deprecates claude-3-sonnet-20240229, the sonnet alias transparently maps to the replacement model without requiring configuration updates.

Can I mix model aliases within a single workflow?

Yes. The repository demonstrates this pattern in .claude/commands/weather-orchestrator.md, where a command uses model: haiku for fast data retrieval while other steps might use inherit or explicit aliases. This heterogeneous approach optimizes costs by using cheaper models for simple steps and expensive models only for reasoning-intensive phases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}