Cc Switch
Manage API providers for Codex and compatible CLI tools with automatic mode detection, pre-switch connectivity tests, and endpoint URL updates.
CC Switch - Dual-Mode Provider Management
A provider management skill that works in two modes automatically:
| Mode | When Active | Data Storage |
|---|---|---|
| cc-switch mode | cc-switch desktop app is installed (~/.cc-switch/cc-switch.db exists) | SQLite database |
| standalone mode | cc-switch is NOT installed | JSON files (~/.cc-switch-skill/) |
The skill automatically detects which mode to use - no manual configuration needed.
Supported Apps
| Application | app_type | Hot-Switch |
|---|---|---|
| Codex | Codex | Endpoint-only |
| Codex | codex | ❌ No |
| Gemini CLI | gemini | ❌ No |
| OpenCode | opencode | ❌ No |
| OpenClaw | openclaw | ❌ No |
Mode Detection
The skill checks for ~/.cc-switch/cc-switch.db:
- Found → Uses SQLite mode (reads from cc-switch database)
- Not found → Uses standalone mode (reads from
~/.cc-switch-skill/)
You can install/remove cc-switch anytime and the skill will automatically adapt.
Storage Locations
cc-switch Mode
- Database:
~/.cc-switch/cc-switch.db - Managed by: cc-switch desktop application
Standalone Mode
- Config:
~/.cc-switch-skill/config.json— Active providers per app - Providers:
~/.cc-switch-skill/providers.json— All configured providers - Presets:
~/.Codex/skills/cc-switch/presets.json— Built-in presets
Core Operations
1. Add Provider
~/.Codex/skills/cc-switch/scripts/add_provider.sh \
--name "MiniMax" \
--app Codex \
--key "sk-xxxx" \
--url "https://api.minimax.com/v1" \
--sonnet "Codex-3-5-sonnet-20241022"
2. List Providers
~/.Codex/skills/cc-switch/scripts/list_providers.sh
~/.Codex/skills/cc-switch/scripts/list_providers.sh --app Codex
Output shows the current mode:
======================================
Providers List
======================================
Mode: [cc-switch mode]
### Codex
ID | Name | Status
--------------------------------------+------------------------------+--------
a1b2c3d4-e5f6-7890-abcd-ef1234567890 | Anthropic Official | 🟢 [Active]
3. Switch Provider (with Pre-flight Connectivity Check)
~/.Codex/skills/cc-switch/scripts/switch_provider.sh \
--app Codex \
--name "MiniMax"
Important: Switching runs a connectivity test first:
- ✅ Test passes → Switch proceeds automatically
- ❌ Test fails → Error details shown, user asked to confirm before proceeding
To skip the connectivity check (advanced use):
~/.Codex/skills/cc-switch/scripts/switch_provider.sh \
--app Codex \
--name "MiniMax" \
--skip-test
4. Delete Provider
~/.Codex/skills/cc-switch/scripts/delete_provider.sh --id provider-uuid
Cannot delete currently active provider - must switch first.
5. Test Provider Connectivity
~/.Codex/skills/cc-switch/scripts/test_connectivity.sh --app Codex --name "MiniMax"
Presets
Built-in provider presets in presets.json work in standalone mode:
| Name | App | Description |
|---|---|---|
| Anthropic Official | Codex, gemini | Official Anthropic API |
| MiniMax Official | Codex | Official MiniMax API |
| Zhipu AI Official | Codex | Official Zhipu AI endpoint |
| DeepSeek Official | Codex | Official DeepSeek API |
Presets are used as templates - you provide your own API key when adding.
Hot-Switching Support
Only Codex supports hot-switching — changes take effect immediately without restarting the terminal.
For all other apps, you must restart the terminal or CLI tool after switching providers.
Workflow
Typical Usage
- Add provider — Use
add_provider.shwith your credentials - Test — Use
test_connectivity.shto verify - Switch — Use
switch_provider.sh(auto-tests first) - List — Use
list_providers.shto see all options
Example Session
User: I want to switch to MiniMax
Codex: Running switch_provider.sh --app Codex --name MiniMax
[Connectivity test runs...]
✅ Connectivity test passed
Switching Codex to MiniMax...
✅ Successfully switched Codex provider to: MiniMax
ℹ️ Codex supports hot-switching - changes take effect immediately!
User: Test the connection
Codex: test_connectivity.sh --app Codex --name MiniMax
[Shows detailed test results]
When Connectivity Fails
User: Switch to TestProvider
Codex: Running switch_provider.sh...
======================================
Connectivity Test FAILED
======================================
Error Details:
HTTP Status: 401
API Endpoint: https://api.test.com/v1
Model: test-model
Response:
{"error": {"type": "authentication_error", "message": "Invalid API key"}}
======================================
⚠️ The connectivity test failed.
Possible causes:
- Invalid API key
- Incorrect base URL
- Model name mismatch
- Network connectivity issues
Do you want to switch to this provider anyway? (yes/no)
CLI Tool Integration
The skill manages provider configurations but updates to CLI tool settings vary:
Codex
switch_provider.sh treats Codex specially:
- It reads the selected provider's
base_url - It does not change cc-switch's active provider state or SQLite rows
- It only merges
~/.Codex/settings.jsonand updates.env.ANTHROPIC_BASE_URL - It preserves the rest of
settings.json
Resulting shape:
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.minimax.com/v1"
}
}
Other CLI Tools
Research the configuration file locations for:
- Codex
- Gemini CLI
- OpenCode
- OpenClaw
Update them with the active provider's API key and base URL manually.
Quick Reference
| Action | Script | Connectivity Check |
|---|---|---|
| Add provider | add_provider.sh | No |
| List all | list_providers.sh | No |
| List by app | list_providers.sh --app <app> | No |
| Switch provider | switch_provider.sh | Yes (pre-flight) |
| Switch (skip test) | switch_provider.sh --skip-test | No |
| Delete provider | delete_provider.sh | No |
| Test connectivity | test_connectivity.sh | Yes (explicit) |
Common Patterns
Adding a New Provider
-
List available presets:
bash jq '.presets[] | select(.name)' ~/.Codex/skills/cc-switch/presets.json -
Add your credentials:
bash ~/.Codex/skills/cc-switch/scripts/add_provider.sh \ --name "My Provider" \ --app Codex \ --key "sk-xxxx" \ --url "https://api.example.com/v1" -
Test before switching:
bash ~/.Codex/skills/cc-switch/scripts/test_connectivity.sh --app Codex --name "My Provider" -
Switch (with automatic test):
bash ~/.Codex/skills/cc-switch/scripts/switch_provider.sh --app Codex --name "My Provider"
Managing Multiple Apps
List all providers across all apps:
~/.Codex/skills/cc-switch/scripts/list_providers.sh
Switch different providers for different apps:
~/.Codex/skills/cc-switch/scripts/switch_provider.sh --app Codex --name MiniMax
~/.Codex/skills/cc-switch/scripts/switch_provider.sh --app codex --name AnotherProvider
Troubleshooting
Script Not Found
Ensure the skill is installed in ~/.Codex/skills/cc-switch/ and scripts are executable:
chmod +x ~/.Codex/skills/cc-switch/scripts/*.sh
Provider Not Found
Double-check the provider name when using --name flag:
~/.Codex/skills/cc-switch/scripts/list_providers.sh
Mode Detection Issues
If you see unexpected mode:
# Check if cc-switch database exists
ls -la ~/.cc-switch/cc-switch.db
# Or check standalone directory
ls -la ~/.cc-switch-skill/
Connectivity Test Always Fails
Check:
- API key is correct and active
- Base URL is accessible from your network
- Model name is valid for the provider
- Network/firewall allows the connection
Test Fails But Provider Works
If you want to switch despite test failure, use --skip-test flag:
~/.Codex/skills/cc-switch/scripts/switch_provider.sh --app Codex --name Provider --skip-test
Architecture Notes
common.sh
All scripts source scripts/common.sh which provides:
- Mode detection (
detect_mode()) - Unified functions (
list_providers(),get_provider_by_name(), etc.) - SQLite-specific functions (
sqlite_*) - Standalone-specific functions (
standalone_*) - Utility functions (
generate_uuid(),get_provider_credentials())
Mode Auto-Switching
You can install or uninstall cc-switch at any time:
- Install cc-switch → Skill automatically switches to SQLite mode on next operation
- Uninstall cc-switch → Skill automatically falls back to standalone mode
No migration needed - the skill adapts to whatever is available.
- Downloads
- Security audit
- Review
- Last updated
- 2mo ago
- Current version
- v1.0.0
- License
- MIT-0
