Custom Model Setup

Override default Claude model selection with specific model versions or organization deployments.

When to Use This Setting

Apply this setting when you need to:

• Pin Claude Code to a specific model version for consistent behavior across team members and sessions
• Test new model versions before rolling them out to the entire development team
• Configure separate models for primary reasoning and fast auxiliary tasks like file summarization Consider alternatives when:
• You want Claude Code to automatically use the latest available model for each capability tier
• Your organization does not have specific model version requirements or compliance constraints

Quick Start

Configuration

Copy
name: custom-model-setup
type: setting
category: global

Example Application

Copy
claude setting:apply custom-model-setup

Example Output

Setting applied. Changes:
- model: claude-3-5-sonnet-20241022
- ANTHROPIC_SMALL_FAST_MODEL: claude-3-5-haiku-20241022

Core Concepts

Model Selection Overview

Aspect	Details
Primary Model	The main model used for code generation, analysis, and reasoning tasks
Small Fast Model	A lighter model used for auxiliary tasks where speed matters more than depth
Model Pinning	Locking to specific dated versions prevents unexpected behavior changes from updates
Deployment Routing	Custom model IDs can route requests to organization-specific deployments

Model Routing Architecture

+---------------------------+
|    Claude Code Session    |
+---------------------------+
         |
    +----+----+
    |         |
    v         v
+--------+ +----------+
| Primary| | Fast     |
| Model  | | Model    |
| (Sonnet| | (Haiku)  |
|  3.5)  | |          |
+--------+ +----------+
    |         |
    v         v
+--------+ +----------+
| Code   | | File     |
| Gen    | | Summary  |
| Review | | Quick    |
| Debug  | | Analysis |
+--------+ +----------+

Configuration

Parameter	Type	Default	Description
model	string	"claude-sonnet-4-20250514"	Primary model identifier for main reasoning tasks
ANTHROPIC_SMALL_FAST_MODEL	string	"claude-haiku-4-20250414"	Model used for fast auxiliary tasks
ANTHROPIC_BASE_URL	string	"https://api.anthropic.com"	API endpoint URL, change for custom deployments
ANTHROPIC_API_KEY	string	N/A	API key for authentication, typically set via environment
description	string	N/A	Human-readable explanation of the model configuration

Best Practices

1. Pin model versions for production workflows - Using dated model identifiers like claude-3-5-sonnet-20241022 ensures that your team experiences consistent behavior. Unpinned model names may resolve to different versions over time.
2. Match the fast model to your latency requirements - The ANTHROPIC_SMALL_FAST_MODEL handles background tasks. If these tasks are not time-sensitive, you can use a more capable model. If speed is critical, Haiku provides the fastest responses.
3. Test model changes in isolation - Before updating the team-wide model configuration, have one developer test the new model version for a full sprint. Document any behavior differences in code generation and error handling.
4. Document your model selection rationale - Include comments explaining why specific model versions were chosen. This helps future team members understand the tradeoffs and makes upgrade decisions easier.
5. Monitor costs across model tiers - Different models have different pricing. Track usage patterns to ensure the model selection balances capability needs with budget constraints.

Common Issues

1. Model not found error - Double-check the model identifier string for typos. Model IDs are case-sensitive and include date suffixes. Verify the model is available in your region and for your API plan.
2. Unexpected behavior after model change - Different model versions may handle edge cases differently. If code generation quality changes after switching models, review the release notes for documented behavior changes.
3. Fast model producing lower quality responses - The small fast model is optimized for speed, not depth. If auxiliary task quality is insufficient, consider upgrading the fast model to a mid-tier option.