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

> Learn Claude Code model aliases like haiku sonnet opus and inherit to control speed cost and reasoning depth for your AI agents and commands.

- Repository: [Shayan Rais/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice)
- Tags: deep-dive
- Published: 2026-03-12

---

**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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/settings.json) defines.

This alias ensures consistency across workflow steps. As documented in [`best-practice/claude-subagents.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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.

```yaml

# 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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/settings.json) file exposes a top-level `model` key that understands these aliases. According to [`best-practice/claude-settings.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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.

```json
{
  "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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.claude/commands/weather-orchestrator.md), where `model: haiku` guarantees fast execution for weather data retrieval steps.

```yaml

# 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.

```bash

# 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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/CLAUDE.md) and [`best-practice/claude-subagents.md`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/best-practice/claude-subagents.md) for maintaining workflow consistency.
- Configuration occurs in three layers: global [`settings.json`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/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`](https://github.com/shanraisshan/claude-code-best-practice/blob/main/.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.