Claude Model Switch (cms)

A CLI tool to switch between different Claude model configurations in ~/.claude/settings.json.

Why?

Claude Code uses environment variables in settings.json to configure which models to use for different tiers (Haiku, Sonnet, Opus). When working with multiple Claude-compatible endpoints (Anthropic native, third-party APIs, local proxies), manually editing settings.json gets tedious. This tool lets you define profiles and switch between them instantly.

Installation

Option 1: Compiled Binary (Recommended)

# Clone and build
git clone <repo-url>
cd claude-model-switch
bun install
bun run compile

# Install globally (requires sudo on most systems)
sudo ln -sf $(pwd)/cms /usr/local/bin/cms

Option 2: From Source

git clone <repo-url>
cd claude-model-switch
bun install
bun run build

# Run with node
node dist/index.js <command>

# Or run directly with bun
bun run src/index.ts <command>

Configuration

Models Config File

Location: ~/.claude/models.json

Create this file to define your model profiles:

{
  "models": {
    "claude-native": {
      "haiku": "claude-3-5-haiku-20241022",
      "sonnet": "claude-sonnet-4-20250514",
      "opus": "claude-opus-4-20250514",
      "baseUrl": "https://api.anthropic.com",
      "authToken": "${ANTHROPIC_API_KEY}"
    },
    "custom-endpoint": {
      "haiku": "custom-model",
      "sonnet": "custom-model",
      "opus": "custom-model",
      "baseUrl": "https://api.example.com/v1",
      "authToken": "your-api-token"
    }
  },
  "defaultModel": "claude-native"
}

Profile Fields

| Field | Required | Description | |-------|----------|-------------| | haiku | Yes | Model ID for Haiku tier (fast/cheap tasks) | | sonnet | Yes | Model ID for Sonnet tier (balanced) | | opus | Yes | Model ID for Opus tier (most capable) | | baseUrl | Yes | API endpoint URL | | authToken | Yes | API key or env var reference (e.g., ${ANTHROPIC_API_KEY}) |

Environment Variables in Auth Token

You can reference environment variables using ${VAR_NAME} syntax:

{
  "authToken": "${ANTHROPIC_API_KEY}"
}

This keeps sensitive tokens out of the config file. The value is written as-is to settings.json, and Claude Code will expand it at runtime.

Commands

cms list

List all available model profiles. The currently active profile is marked with *, and the default profile is marked with (default).

$ cms list
Available model profiles:

  claude-native * (default)
  custom-endpoint
  local-proxy

* = currently active

cms current

Show the currently active model configuration.

$ cms current
Current model: claude-native

Configuration:
  Haiku:   claude-3-5-haiku-20241022
  Sonnet:  claude-sonnet-4-20250514
  Opus:    claude-opus-4-20250514
  Base URL: https://api.anthropic.com
  Auth:    ${ANTHROPIC_API_KEY}

If the current settings don't match any known profile, it shows (unknown profile).

cms switch <name>

Switch to a different model profile. This updates ~/.claude/settings.json with the profile's configuration.

$ cms switch custom-endpoint
Switched to model profile: custom-endpoint
  Haiku:   custom-model
  Sonnet:  custom-model
  Opus:    custom-model

cms add <name>

Interactively add a new model profile. Prompts for each field with sensible defaults.

$ cms add my-provider

Adding new model profile: my-provider

Enter model configuration (press Enter for defaults where shown):

Haiku model ID [claude-3-5-haiku-20241022]: my-haiku-model
Sonnet model ID [claude-sonnet-4-20250514]: my-sonnet-model
Opus model ID [claude-opus-4-20250514]: my-opus-model
API base URL [https://api.anthropic.com]: https://my-api.example.com
Auth token (or ${ENV_VAR}) [${ANTHROPIC_API_KEY}]: ${MY_API_KEY}

Profile "my-provider" added successfully.

Configuration:
  Haiku:   my-haiku-model
  Sonnet:  my-sonnet-model
  Opus:    my-opus-model
  Base URL: https://my-api.example.com
  Auth:    ${MY_API_KEY}

Run `cms switch my-provider` to activate this profile.

cms remove <name>

Remove a profile from the configuration.

$ cms remove old-provider
Removed profile: old-provider

If the removed profile was the default, the first remaining profile becomes the new default.

Options

All commands support these global options:

| Option | Description | |--------|-------------| | -c, --config <path> | Custom models.json path (default: ~/.claude/models.json) | | -s, --settings <path> | Custom settings.json path (default: ~/.claude/settings.json) |

Example:

cms list -c ./test-models.json -s ./test-settings.json

How It Works

1. Config Storage: Model profiles are stored in ~/.claude/models.json
2. Settings File: The tool modifies ~/.claude/settings.json, specifically the env object
3. Detection: When running list or current, the tool compares current settings against profiles to detect which is active

Settings.json Structure

The tool manages these environment variables in settings.json:

{
  "env": {
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-3-5-haiku-20241022",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-20250514",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-20250514",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "ANTHROPIC_AUTH_TOKEN": "${ANTHROPIC_API_KEY}"
  }
}

Other settings are preserved when switching profiles.

Examples

Switch Between Native and Custom Endpoint

# Use Anthropic's API directly
cms switch claude-native

# Switch to a custom provider
cms switch my-custom-provider

# Check what's active
cms current

Add a Local Proxy

cms add local

# When prompted:
# - Haiku: claude-3-5-haiku-20241022
# - Sonnet: claude-sonnet-4-20250514
# - Opus: claude-opus-4-20250514
# - Base URL: http://localhost:8080
# - Auth: (leave empty or use a dummy token)

Use Different Models per Tier

Some providers let you mix models:

{
  "models": {
    "mixed-config": {
      "haiku": "fast-cheap-model",
      "sonnet": "balanced-model",
      "opus": "most-capable-model",
      "baseUrl": "https://api.example.com",
      "authToken": "${API_KEY}"
    }
  }
}

Development

Build

bun run build    # Build to dist/index.js
bun run compile  # Create standalone binary 'cms'

Project Structure

src/
├── index.ts              # CLI entry point (Commander.js)
├── commands/
│   ├── list.ts           # List profiles
│   ├── current.ts        # Show active model
│   ├── switch.ts         # Switch profile
│   ├── add.ts            # Interactive profile creation
│   └── remove.ts         # Delete profile
├── lib/
│   ├── config.ts         # Load/save models.json
│   ├── settings.ts       # Load/save settings.json
│   └── detection.ts      # Detect current profile from settings
└── types/
    └── index.ts          # TypeScript interfaces

License

MIT