Skip to content

Launcher Model Configuration

Default Model Behavior

The amplihack launcher uses sonnet[1m] as the default model when launching Claude Code. This provides the optimal balance of performance, extended context window, and cost-effectiveness for most development tasks.

Model Selection Priority

When the launcher determines which model to use, it follows this strict priority order:

  1. --model Flag (highest priority)
  2. Explicitly specified model via command-line flag
  3. Example: amplihack launch --model opus

  4. Overrides environment variable and hardcoded default

  5. AMPLIHACK_DEFAULT_MODEL Environment Variable

  6. Set in your shell environment
  7. Example: export AMPLIHACK_DEFAULT_MODEL=opus

  8. Overrides hardcoded default but not command-line flag

  9. Hardcoded Default (lowest priority)

  10. sonnet[1m] is used when no other configuration is present
  11. Provides sensible default for most development work

Usage Examples

Using the Default Model

# Uses sonnet[1m] by default
amplihack launch

Override with Command-Line Flag

# Use Opus model with extended context
amplihack launch --model opus[1m]

# Use Haiku for quick tasks
amplihack launch --model haiku

# Use standard Sonnet without extended context
amplihack launch --model sonnet

Override with Environment Variable

# Set default model for all amplihack sessions
export AMPLIHACK_DEFAULT_MODEL=opus[1m]

# Now all launches use Opus by default
amplihack launch

# Still can override with flag
amplihack launch --model haiku

Available Models

Model Context Best For
sonnet[1m] 1M tokens Default - most development tasks
sonnet 200K tokens Standard development work
opus[1m] 1M tokens Complex architecture, critical code
opus 200K tokens High-quality reasoning
haiku 200K tokens Quick tasks, simple operations

Configuration Persistence

Model selection is per-session only. Each time you launch amplihack, the priority hierarchy is evaluated fresh:

  • Command-line flags apply to that session only
  • Environment variables persist across shell sessions (until unset)
  • Hardcoded default is always available as fallback

To permanently change your default model, set the environment variable in your shell profile:

# Add to ~/.bashrc or ~/.zshrc
export AMPLIHACK_DEFAULT_MODEL=opus[1m]

# Reload shell configuration
source ~/.bashrc  # or source ~/.zshrc

Checking Active Model

The active model is displayed in the statusline at the bottom of Claude Code:

~/src/amplihack (main → origin) Sonnet[1m] 🎫 234K 💰$1.23 ⏱12m

For more information about the statusline, see STATUSLINE.md.

Troubleshooting

Environment variable not being respected

Problem: You set AMPLIHACK_DEFAULT_MODEL but the default sonnet[1m] is still used.

Solution:

  1. Verify the variable is exported: echo $AMPLIHACK_DEFAULT_MODEL
  2. Check for command-line flags that override it
  3. Ensure you've reloaded your shell after setting it

Invalid model name

Problem: Error when specifying an invalid model name.

Solution: Use one of the valid model names listed in the "Available Models" table above. Model names are case-sensitive.