cc-switch-helper

cc-switch-helper

English ｜ 中文文档

Overcomes the global single-config limitation of the original CC-Switch, enabling per-terminal, per-window binding of different API keys and models — multiple sessions running in parallel without interference.

The native CC-Switch shares one global API config across all terminals — switching providers changes every window at once. This tool provides session-level isolation: one terminal on a personal key, another on a company key, running side by side with no conflicts.

Why?

CC-Switch is a great tool for managing Claude Code providers, but switching providers changes the global config — every running Claude Code instance picks up the change.

ccs takes a different approach: it passes the provider settings directly to each claude process. This means you can run DeepSeek in one terminal and GLM in another, at the same time, without ever touching the global config.

Terminal 1: ccs deep     → Claude Code running DeepSeek
Terminal 2: ccs glm      → Claude Code running GLM
Terminal 3: ccs zcy      → Claude Code running your custom provider

Each window is independent. Switch providers in one — the others stay untouched.

CC-Switch provider configuration panel:

Features

• Session-level config isolation — run different API keys, providers, and models across multiple terminals/windows simultaneously, no interference
• Interactive menu — arrow keys to pick a provider, no need to remember names
• Fuzzy match — ccs deep matches “DeepSeek”, ccs mini matches “Minimax”
• Cross-platform — works on macOS, Linux, and Windows (PowerShell / CMD / Git Bash)
• Zero config — reads directly from your CC-Switch database, compatible with existing key groups and relay configs
• Non-invasive — does not modify CC-Switch source code; CC-Switch upgrades won’t affect this tool

Prerequisites

1. CC-Switch installed with at least one Claude provider configured
2. Claude Code CLI installed
3. Node.js ≥ 22.22

Install

npm install -g cc-switch-helper

This registers the ccs command globally.

Prefer living on the edge? Install the unreleased development version straight from GitHub:

npm install -g luckybilly/cc-switch-helper

Usage

ccs                       # Interactive provider selection
ccs <name>                # Fuzzy-match provider by name
ccs <name> -- <args...>   # Pass extra arguments to claude
ccs --no-skip             # Launch without --dangerously-skip-permissions
ccs --list                # List all configured providers
ccs --version             # Print version
ccs --help                # Show help

Examples

# Pick from an interactive menu
ccs

# Launch with a specific provider (case-insensitive fuzzy match)
ccs zcy
ccs DeepSeek
ccs glm

# Pass extra arguments to claude (everything after --)
ccs zcy -- --resume
ccs DeepSeek -- -p "hello world"

# Launch without --dangerously-skip-permissions (review each permission)
ccs zcy --no-skip

# See all your configured providers
ccs --list

Alias to cc

If you prefer the shorter cc command, add an alias to your shell config:

# ~/.zshrc or ~/.bashrc
alias cc=ccs

Note: cc is also the system C compiler on macOS/Linux. The alias takes priority in your shell, but be aware if you work with C projects.

How it works

1. Reads providers from CC-Switch’s SQLite database (~/.cc-switch/cc-switch.db), plus the shared common_config_claude (hooks, statusLine, permissions, plugins, …) stored in its settings table
2. Builds the effective settings the same way CC-Switch does on switch — json_deep_merge(provider.settings_config, common_config) when the provider’s meta.commonConfigEnabled is true (and the common config is non-empty), otherwise the provider’s settings_config verbatim. This is a recursive deep merge; on any leaf conflict common config wins.
3. Launches claude --settings <json> --dangerously-skip-permissions

Each window gets exactly what CC-Switch would write to ~/.claude/settings.json for that provider — including hooks/plugins/statusLine when the provider shares the common config, and a bare env for providers that opt out.

--dangerously-skip-permissions is a built-in Claude Code flag that skips per-action permission prompts for a smoother experience. Add --no-skip to restore per-action approval, useful when you want tighter permission control.

Platform support

Platform	Shell	Status
macOS	zsh, bash	✅
Linux	bash, zsh, fish	✅
Windows	PowerShell	✅
Windows	CMD	✅
Windows	Git Bash	✅

Supported CPU architectures: x64 and arm64.

FAQ

Q: Does ccs conflict with switching providers in CC-Switch?

A: No. ccs pins the provider config (model, API key, etc.) to the process at launch, so switching the default provider can’t redirect a session that’s already running.

One exception: config items added to settings.json after the switch get auto-loaded into the old session — to be safe, start a fresh ccs session after switching.

Q: How do I know which provider a window is using?

A: ccs prints → Launching [provider-name] on startup. The terminal title bar also shows it.

Q: What’s the difference between default and --no-skip?

A: Default includes --dangerously-skip-permissions, which skips Claude Code’s per-action permission prompts. --no-skip restores per-action approval, useful for tighter security control.

License

MIT