# Model Configuration

> Learn about the Claude Code model configuration, including model aliases like `opusplan`

## Available Models

For the `model` setting in Claude Code, you can configure either:
- A **model alias**
- A **model name** (full model name for Anthropic API, inference profile ARN for Bedrock, deployment name for Foundry, or version name for Vertex)

## Model Aliases

| Model alias      | Behavior                                                                                                 |
| :--------------- | :------------------------------------------------------------------------------------------------------- |
| **`default`**    | Recommended model setting, depending on your account type                                                |
| **`sonnet`**     | Uses the latest Sonnet model (currently Sonnet 4.5) for daily coding tasks                               |
| **`opus`**       | Uses Opus model (currently Opus 4.5) for specialized complex reasoning tasks                             |
| **`haiku`**      | Uses the fast and efficient Haiku model for simple tasks                                                 |
| **`sonnet[1m]`** | Uses Sonnet with a 1 million token context window for long sessions                                      |
| **`opusplan`**   | Special mode that uses `opus` during plan mode, then switches to `sonnet` for execution                  |

## Setting Your Model

You can configure your model in several ways, listed in order of priority:

1. **During session** - Use `/model <alias|name>` to switch models mid-session
2. **At startup** - Launch with `claude --model <alias|name>`
3. **Environment variable** - Set `ANTHROPIC_MODEL=<alias|name>`
4. **Settings** - Configure permanently in your settings file using the `model` field

### Examples

```bash
# Start with Opus
claude --model opus

# Switch to Sonnet during session
/model sonnet
```

Settings file:
```json
{
  "permissions": {
    ...
  },
  "model": "opus"
}
```

## Special Model Behavior

### `default` Model Setting

The behavior of `default` depends on your account type. For certain Max users, Claude Code will automatically fall back to Sonnet if you hit a usage threshold with Opus.

### `opusplan` Model Setting

The `opusplan` model alias provides an automated hybrid approach:

- **In plan mode** - Uses `opus` for complex reasoning and architecture decisions
- **In execution mode** - Automatically switches to `sonnet` for code generation and implementation

This gives you the best of both worlds: Opus's superior reasoning for planning, and Sonnet's efficiency for execution.

### Extended Context with [1m]

For Console/API users, the `[1m]` suffix can be added to full model names to enable a 1 million token context window:

```bash
# Example of using a full model name with the [1m] suffix
/model anthropic.claude-sonnet-4-5-20250929-v1:0[1m]
```

**Note**: Extended context models have different pricing.

## Checking Your Current Model

You can see which model you're currently using:
1. In the status line (if configured)
2. In `/status`, which also displays your account information

## Environment Variables

You can use environment variables to control model names that aliases map to. These must be full **model names** (or equivalent for your API provider).

| Environment variable             | Description                                                                   |
| :------------------------------- | :---------------------------------------------------------------------------- |
| `ANTHROPIC_DEFAULT_OPUS_MODEL`   | The model to use for `opus`, or for `opusplan` when Plan Mode is active       |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | The model to use for `sonnet`, or for `opusplan` when Plan Mode is not active |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL`  | The model to use for `haiku`, or background functionality                     |
| `CLAUDE_CODE_SUBAGENT_MODEL`     | The model to use for subagents                                                |

**Note**: `ANTHROPIC_SMALL_FAST_MODEL` is deprecated in favor of `ANTHROPIC_DEFAULT_HAIKU_MODEL`.

## Prompt Caching Configuration

Claude Code automatically uses prompt caching to optimize performance and reduce costs. You can disable prompt caching globally or for specific model tiers:

| Environment variable            | Description                                                                    |
| :------------------------------ | :----------------------------------------------------------------------------- |
| `DISABLE_PROMPT_CACHING`        | Set to `1` to disable prompt caching for all models (takes precedence)         |
| `DISABLE_PROMPT_CACHING_HAIKU`  | Set to `1` to disable prompt caching for Haiku models only                     |
| `DISABLE_PROMPT_CACHING_SONNET` | Set to `1` to disable prompt caching for Sonnet models only                    |
| `DISABLE_PROMPT_CACHING_OPUS`   | Set to `1` to disable prompt caching for Opus models only                      |

The global `DISABLE_PROMPT_CACHING` setting takes precedence over model-specific settings. Per-model settings are useful for selective control, such as when debugging specific models or working with cloud providers that may have different caching implementations.

## Model Selection for Subagents

Built-in subagents use specific models:
- **Explore**: Haiku (fast, low-latency)
- **Plan**: Inherits from main conversation
- **General-purpose**: Inherits from main conversation

For custom subagents, specify the model in frontmatter:
```yaml
---
name: my-agent
model: sonnet
---
```

Or use:
- `haiku` - Fast, efficient
- `opus` - Most capable
- `sonnet` - Balanced
- `inherit` - Use main conversation model (default)

## Grid Integration Opportunities

<!-- Placeholder for Grid-specific integration notes -->