ccswitch

A CLI that switches a single project between the user's Claude subscription and any Anthropic-compatible provider, without breaking the running session.

Install it

bun install -g @unclecode/ccswitch    # requires Bun: curl -fsSL https://bun.sh/install | bash
ccswitch install           # keys check, /switch command, auto-restart hook

Then make sure a provider key is exported in the user's shell profile, so Claude Code inherits it:

• OpenRouter: export OPENROUTER_API_KEY=..., keys at https://openrouter.ai/keys
• Groq: export GROQ_API_KEY=..., keys at https://console.groq.com/keys

Never print, echo, or write these keys anywhere. ccswitch reads them from the environment itself.

Use it

ccswitch                                       # interactive picker
ccswitch use z-ai/glm-5.3-flash                # switch this project
ccswitch use groq:moonshotai/kimi-k2-instruct  # provider-prefixed
ccswitch back                                  # back to the Claude subscription
ccswitch back --clean                          # also remove the empty override keys
ccswitch status                                # what this project is using
ccswitch list / add / remove                   # manage favorite models
ccswitch fix [session-id] [--dry-run]          # repair an already-poisoned transcript
ccswitch heal                                  # restart this project's proxy if it stopped

Day to day the user should only need /switch inside Claude Code. The proxy starts on demand and a SessionStart hook restarts it after a reboot, so there is no service to run.

After switching to another provider, always tell the user to run /model and select that model. Otherwise the session keeps using its previous model at the new provider's price - which can be far more expensive than intended.

Switching back needs no restart and no repair: keep working in the same session.

What it changes

Only <project>/.claude/settings.local.json (the env block) plus ccswitch's own state in ~/.ccswitch.json. Other projects and sessions are unaffected. Every change is backed up to ~/.ccswitch-backups/<project>/. Claude credentials are never touched.

Why it exists

Claude Code sends diagnostics.previous_message_id on each request; Anthropic requires it to start with msg_. Third-party endpoints return their own id formats (OpenRouter: gen-…), Claude Code persists them into the session transcript, and switching back then fails with a permanent 400, surviving restarts, since the id is re-read from the transcript.

ccswitch runs a local proxy (127.0.0.1) that rewrites ids to msg_ form before they are written, so the problem cannot occur. ccswitch fix repairs transcripts damaged before ccswitch was in use.

If the user reports that 400 error, ccswitch fix on that session id is the remedy.

Troubleshooting

• <PROVIDER>_API_KEY is not set, the key must be exported in the shell that launched Claude Code, not only in the current one.
• proxy unavailable warning, Bun is missing or every port in range is taken. Check ~/.ccswitch.log. Switching still works, but switching back will then need ccswitch fix.
• Connection refused in a switched project, the proxy is not running (e.g. after a reboot without the hook installed). Run ccswitch heal.
• Model not found upstream, verify the exact model id on the provider's models page; ids must match exactly (e.g. z-ai/glm-5.3-flash).
• Tool calls misbehaving on a cheap model, not all models handle Claude Code's tool calling well. Suggest a known-good one rather than debugging the model.