🔀 claude-code-model-switch

Switch the AI provider & model that Claude Code uses — across every project, with one command.

---

Claude Code is configured per project through ANTHROPIC_* environment keys in .claude/settings.json. Want to hop from OpenRouter's free hy3 to Z.ai's glm-4.7-flash, or point all your projects at a local Ollama? Today you'd hand-edit base URLs, API keys, and model IDs in every settings file. ✍️

Note

claude-code-model-switch does it for you — interactively or from the command line — and keeps a clean, shareable library of provider configs.

---

✨ Features

🚀	Feature
🔀	Provider + model switching in one step — OpenRouter, Z.ai/GLM, Ollama, HuggingFace, Kimi (Moonshot), and local gateways like Free-Way
🆓	Free-tier first — bundled configs focus on providers with real free/free-tier access for agentic coding
📦	Bulk updates — --all and --sync-auth rewrite every .claude/settings.json under your projects root at once
🧩	Extensible — add any Anthropic-compatible (or gateway-routed) provider by dropping a JSON file into .providers/
🔒	Safe to share — configs ship as templates with placeholder tokens; real keys live in ~/.config/model-switch/.providers/ and are git-ignored
🪶	Zero runtime deps — just bash, jq, and tput (standard on macOS/Linux)

---

🚀 Install

git clone https://github.com/tjrrich/claude-code-model-switch.git
cd claude-code-model-switch
./install.sh

Tip

install.sh symlinks set-model.sh into ~/.local/bin, optionally adds a set-model shell alias, and runs init to scaffold your config.

---

⚡ Quick start

set-model.sh                      # 🎛️ interactive: pick a provider → pick a model (current dir)
set-model.sh --list-providers     # 📋 show everything you've configured

# 🤖 non-interactive:
set-model.sh --provider zai --apply glm-4.7-flash
set-model.sh --provider openrouter --apply tencent/hy3:free --all
set-model.sh --provider ollama --apply llama3.1:70b --project my-app
set-model.sh --sync-auth          # 🔁 push the active provider's URL+key to every project

On first run, init copies template configs into ~/.config/model-switch/.providers/ and writes config.json. Edit the tokens in those files, then:

set-model.sh --list-providers

📖 Commands

Command	What it does
set-model.sh	Interactive provider → model picker for the current project
set-model.sh init	Scaffold .providers/, config.json, and models.md
set-model.sh --list-providers	List configured providers
set-model.sh --provider P --apply M	Set provider P + model M in the current project
set-model.sh --provider P --apply M --project N	Same, for project N under projects_root
set-model.sh --provider P --apply M --all	Same, for every project
set-model.sh --sync-auth	Refresh only the base URL + token on every project
set-model.sh --home DIR	Use an explicit config home (overrides auto-detect)

---

🖥️ Example session

$ set-model.sh --list-providers

Configured providers (~/.config/model-switch/.providers)
  • openrouter   - OpenRouter (free)
  • zai          - Z.ai (free tier)
  • ollama       - Ollama (local)
  • huggingface  - HuggingFace
  • freeway      - Free-Way (local gateway)

$ set-model.sh --provider zai --apply glm-4.7-flash

  Applying (provider: Z.ai (free tier)):
  ✓ my-app → glm-4.7-flash (Z.ai (free tier))

---

🧠 How it works

Claude Code reads these keys from each project's .claude/settings.json:

Key	Purpose
ANTHROPIC_BASE_URL	Provider endpoint
ANTHROPIC_AUTH_TOKEN	Provider API key
ANTHROPIC_MODEL	Model ID
ANTHROPIC_DEFAULT_{HAIKU,SONNET,OPUS}_MODEL	Sub-agent mappings (via a provider's extra_env)

Each provider is one JSON file under $MODEL_SWITCH_HOME/.providers/<name>.json. The tool writes the right combination into your settings files for you.

📂 Where config lives

$MODEL_SWITCH_HOME is resolved in this order:

1. --home <dir> / the MODEL_SWITCH_HOME env var (if set)
2. ~/.config/model-switch (if it already exists)
3. ~/Developer (if it exists and has a .providers/ dir — backward compat)
4. otherwise ~/.config/model-switch (created by init)

config.json (optional) holds default_provider and projects_root (where the tool scans for .claude/settings.json files).

---

🛠️ Adding or editing a provider

Copy a template, fill in your token, done:

cp examples/providers/zai.example.json ~/.config/model-switch/.providers/zai.json
# ✏️ edit the "token" field, then:
set-model.sh --provider zai --apply glm-4.7-flash

Provider config format:

{
  "display_name": "OpenRouter (free)",
  "base_url": "https://openrouter.ai/api",
  "token": "<your-openrouter-key>",
  "endpoint_style": "anthropic",
  "models": [
    { "id": "tencent/hy3:free", "context": "256k", "notes": "Recommended" }
  ],
  "extra_env": { "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.7-flash" }
}

Field	Meaning
display_name	Shown in menus
base_url	Provider endpoint Claude Code talks to
token	API key (plaintext — keep this file private!)
endpoint_style	anthropic (works directly) or openai (⚠️ needs a gateway)
models[]	Selectable models: id, context, notes
extra_env	Extra env vars merged into settings (e.g. Z.ai sub-agent mappings)

---

🌐 Providers at a glance

Provider	Free tier	Notes
OpenRouter	~20 :free models	tencent/hy3:free recommended; NVIDIA free models are rate-limited
Z.ai	GLM flash models	glm-4.7-flash / glm-4.5-flash are FREE; glm-5.2 flagship is paid
Ollama	whatever you pull	Local, no network/quota
HuggingFace	token + tiny credit	⚠️ OpenAI-compatible — does not work directly in Claude Code; use via Free-Way
Free-Way	aggregates many free tiers	Local Anthropic-native gateway (localhost:8787) — the "omnirouter" that works
Kimi	paid API key	Anthropic-compatible endpoint (api.moonshot.ai/anthropic)
Groq	free tier available	⚠️ OpenAI-compatible — does not work directly in Claude Code; use via Free-Way or LiteLLM
Gemini	free tier available	⚠️ OpenAI-compatible — does not work directly in Claude Code; use via Free-Way or LiteLLM
OmniRoute	90+ free tiers (40+ free forever)	Gateway aggregating 1.53B free tokens/month from 43 provider pools — use with set-model --provider omniroute-free --auto

Tip

The deeper write-up — free-model lists, Z.ai pricing reality, Free-Way setup — lives in examples/models.example.md. Copy it to models.md for your own notes.

---

🔒 Security

Warning

API tokens are stored in plaintext in $MODEL_SWITCH_HOME/.providers/*.json. Keep that directory private and never commit it — the .gitignore already excludes .providers/ and config.json.

Important

Only the templates (examples/providers/*.example.json) carry placeholder tokens and are safe to publish. Real keys never enter the repo.

---

🤝 Contributing

Pull requests welcome — new provider templates, model-list updates, and bug fixes are all appreciated. Please keep real tokens out of any config you commit (use the *.example.json format).

📄 License

MIT © claude-code-model-switch contributors.