[FEATURE] Automatic Model Switching for Plan Mode

[generik0]

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Feature Request: Automatic Model Switching for Plan Mode

Summary

Add configuration to automatically switch between models based on workflow phase (planning vs execution), optimizing for both cost and capability.

Problem

Currently, users must manually switch models using /model command when transitioning between planning and execution phases. This leads to:

1. Suboptimal model usage: Users often stay on one model for entire session
2. Cost inefficiency: Using Opus 4.5 for simple execution tasks burns budget ~5x faster
3. Missed opportunities: Not using Opus for complex planning when it would add value
4. Manual overhead: Remembering to switch models interrupts flow

Proposed Solution

Enable automatic model switching based on workflow phase:

• Plan Mode (EnterPlanMode) → Use specified planning model (e.g., Opus 4.5)
• Execution Mode (normal operation) → Use specified execution model (e.g., Sonnet 4.5)
• Quick Tasks (optional) → Use fast model (e.g., Haiku)

Use Cases

Use Case 1: Architecture & Implementation

User: "Implement user authentication with OAuth"

Claude Code:
1. Enters plan mode → AUTO-SWITCHES to Opus 4.5
2. Creates comprehensive architectural plan
3. Exits plan mode → AUTO-SWITCHES to Sonnet 4.5
4. Executes implementation efficiently

Benefit: Best model for planning, cost-effective execution

Use Case 2: Complex Refactoring

User: "Refactor this monolith into microservices"

Claude Code:
1. Plan mode (Opus) → Design service boundaries, data flow, migration strategy
2. Execution mode (Sonnet) → Implement refactoring, run tests, create PRs

Benefit: Opus for complex decisions, Sonnet for code changes

Use Case 3: Simple Tasks

User: "Fix this typo in README"

Claude Code:
→ Stays in Sonnet/Haiku (no plan mode needed)

Benefit: No unnecessary model escalation

Proposed Solution

Proposed Configuration

Option A: Settings File

.claude/settings.json:

{
  "models": {
    "plan_mode": "opus",
    "execution_mode": "sonnet",
    "quick_tasks": "haiku"
  },
  "auto_switch_models": true
}

Option B: Environment Variables

export CLAUDE_PLAN_MODEL="opus"
export CLAUDE_EXEC_MODEL="sonnet"
export CLAUDE_AUTO_SWITCH="true"

Option C: CLI Flag

claude code --plan-model opus --exec-model sonnet --auto-switch

Implementation Details

When to Switch

Switch to Plan Model:

• EnterPlanMode tool is invoked
• User explicitly requests planning ("plan the implementation...")
• Task complexity score exceeds threshold (optional)

Switch to Execution Model:

• ExitPlanMode tool is invoked
• Plan is approved by user
• Direct code modification commands (Write, Edit, Bash for git operations)

Switch to Quick Model (optional):

• Simple read operations (Read, Glob, Grep)
• Documentation-only changes
• Running tests/linting

User Control

Users should be able to:

1. Override: Manual /model command always takes precedence
2. Disable: Set auto_switch_models: false
3. Lock: /model opus --lock prevents auto-switching for session
4. Review: See which model is active in status line/prompt

Status Line Integration

Show active model and switching events:

[Opus 4.5] Planning... → Implementation plan ready
[Switching to Sonnet 4.5]
[Sonnet 4.5] Executing... → 5 files modified

Cost/Performance Analysis

Example Session: "Implement OAuth Authentication"

Without Auto-Switching (All Opus):

• Planning: 50K tokens @ Opus rates = $3.75
• Execution: 200K tokens @ Opus rates = $15.00
• Total: $18.75

With Auto-Switching (Opus → Sonnet):

• Planning: 50K tokens @ Opus rates = $3.75
• Execution: 200K tokens @ Sonnet rates = $3.00
• Total: $6.75 (64% cost reduction)

Without Auto-Switching (All Sonnet):

• Planning: 50K tokens @ Sonnet rates = $0.75
• Execution: 200K tokens @ Sonnet rates = $3.00
• Total: $3.75
• Trade-off: Lower quality planning, potential rework costs

Benefits

1. Cost Optimization: Use expensive models only when needed
2. Quality Optimization: Best model for each phase
3. User Experience: Seamless transitions, no manual intervention
4. Flexibility: User can override or disable as needed
5. Transparency: Clear visibility into model usage

Alternative Solutions

Alternatives Considered

Alternative 1: Always Ask User

Claude: "This looks complex. Switch to Opus for planning? (y/n)"

Drawback: Interrupts flow, requires user decision

Alternative 2: Token Budget Thresholds

Automatically downgrade when approaching token limits. Drawback: Doesn't optimize for task type, reactive not proactive

Alternative 3: Per-Tool Model Selection

Each tool (Read, Write, Bash) specifies preferred model. Drawback: Too granular, hard to maintain

Related Features

• [ ] Model performance analytics (track which model was used for what)
• [ ] Cost tracking per session
• [ ] Recommend model switches based on task complexity
• [ ] Custom model presets (e.g., "architect" = opus+sonnet)

Questions for Maintainers

1. Should auto-switching be opt-in or opt-out?
2. Should quick_tasks auto-switching be a separate flag?
3. How should this interact with MCP servers that might specify model preferences?
4. Should project-level settings override user-level settings?

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Example User Stories

As a solo developer, I want Opus for architecture decisions and Sonnet for implementation, so I can maximize quality while managing costs.

As a team lead, I want to configure default models for my team's projects, so everyone follows cost-effective best practices.

As a cost-conscious user, I want to use Haiku for simple tasks and Sonnet for complex ones, reserving Opus only for critical planning.

Success Metrics

• % of users who enable auto-switching
• Average cost reduction per session
• User satisfaction with automatic transitions
• Frequency of manual overrides (high = poor auto-detection)

Additional Context

Additional Context

This feature would be particularly valuable for:

• Large refactoring projects (plan with Opus, execute with Sonnet)
• API design (plan with Opus, implement with Sonnet)
• Architecture decisions (Opus) vs bug fixes (Sonnet/Haiku)
• Complex CI/CD setup (plan with Opus) vs routine updates (Sonnet)