CC Switch - GravitexAI Documentation

1. Overview

CC Switch is a Tauri 2-based desktop app that unifies management of Claude Code, Codex CLI, Gemini CLI, OpenCode and OpenClaw. Switch API providers, models and keys through a GUI — no more hand-editing ~/.config/*, TOML or JSON files across five different tools.

One-click switching

Manage 5 CLI tools in one GUI — no more manual config editing

Multi-model aggregation

Pair with GravitexAI for one key to Claude / GPT / Gemini / Kimi

Usage tracking

Built-in Usage Dashboard for spend, requests and token usage

Smart failover

Local proxy with hot-switching, auto-failover and circuit breaking

Project info

Repo: github.com/farion1231/cc-switch
License: MIT
Author: Jason Young (farion1231)

2. Core Features

2.1 Provider management

50+ presets built-in (including AWS Bedrock, NVIDIA NIM, etc.)
Custom gateway support (which is how GravitexAI plugs in)
One-click switching, drag-to-reorder, import/export configs
System-tray quick access

2.2 MCP server management

Centrally manage MCP server configs across all CLI tools
Two-way sync — change once, applied everywhere

2.3 More

Feature	Description
Prompts manager	Markdown editor with cross-app sync
Skills installer	Install from GitHub repo or ZIP file
Session browser	View and resume conversation history
Cloud sync	Dropbox, OneDrive, iCloud, WebDAV
Deep link	`ccswitch://` for one-click config import

3. Quick Start

Step 1 — Install CC Switch

macOS
Windows
Linux

Homebrew:

brew install --cask cc-switch

Or download the DMG from GitHub Releases.

# Debian / Ubuntu
sudo dpkg -i cc-switch_*.deb

# Fedora / RHEL
sudo rpm -i cc-switch_*.rpm

# Arch Linux
paru -S cc-switch-bin

AppImage and Flatpak are also available.

System requirements: Windows 10+, macOS 10.15 (Catalina)+, Ubuntu 22.04+ / Debian 11+ / Fedora 34+.

Step 2 — Get a GravitexAI key

Open the GravitexAI console and register or log in.

Create a token

Visit API Keys and click “Create new token”.

Copy the key

Copy the generated key (format sk-xxxxxxxxxx) and store it safely.

Step 3 — Configure GravitexAI in CC Switch

Open Provider management

Launch CC Switch, open the Provider page, click “Add”, and choose Custom Gateway.

Fill in the form

Field	Value
Name	`GravitexAI`
API URL	`https://api.gravitex.ai`
API Key	Paste the key from Step 2
Enabled apps	At least enable Claude Code (turn on Codex / Gemini CLI / OpenCode / OpenClaw as needed)

Each CLI tool expects a slightly different Base URL:

Claude Code: https://api.gravitex.ai (no /v1)
Codex CLI / OpenCode: https://api.gravitex.ai/v1 (must end with /v1)
Gemini CLI: https://api.gravitex.ai (no /v1)

CC Switch usually applies the right format per app, but if you set it manually, use the table above.

Save

Click “Add”. CC Switch syncs this configuration to the config files of every CLI tool you enabled.

Step 4 — Add models

Add the GravitexAI model IDs you intend to use: Claude — standard models

Display name	Model ID	Notes
Claude Opus 4.7	`claude-opus-4-7`	Latest flagship — top choice for complex tasks
Claude Sonnet 4.6	`claude-sonnet-4-6`	Strong coding ability, best value
Claude Sonnet 4.5	`claude-sonnet-4-5-20250929`	200K long context
Claude Haiku 4.5	`claude-haiku-4-5-20251001`	Fast and light — great for the haiku thread

GPT / Gemini / Kimi(mix and match under the same provider)

Display name	Model ID	Notes
GPT 5.5	`gpt-5.5`	OpenAI’s latest flagship
GPT 5.1 Codex	`gpt-5.1-codex`	Codex-only — pair with Responses API in OpenCode
Gemini 3.5 Flash	`gemini-3.5-flash`	High throughput / low latency
Gemini 3.1 Pro Preview	`gemini-3.1-pro-preview`	Deep reasoning
Kimi K2	`kimi-k2-250905`	Great price/perf for long text and Chinese tasks

Model picks:

Daily coding: claude-sonnet-4-6
Complex architecture: claude-opus-4-7
Quick Q&A / haiku thread: claude-haiku-4-5-20251001
Cost-optimized: kimi-k2-250905 or gemini-3.5-flash

See the full ID list in the GravitexAI model catalog.

Step 5 — Switch and launch a CLI

With GravitexAI set as the current Provider, every enabled CLI tool automatically picks up the configuration. Launch any of them:

# Claude Code
claude

# Codex
codex

# Gemini CLI
gemini

# OpenCode
opencode

4. Usage Guide

4.1 Manage multiple CLI tools

CC Switch can drive these tools concurrently:

Tool	Detailed config
Claude Code	/en/integrations/claude-code
Codex CLI	/en/integrations/codex
Gemini CLI	/en/integrations/gemini-cli
OpenCode	/en/integrations/open-code
OpenClaw	/en/integrations/openclaw

All tools share the same Provider config — switching takes effect everywhere.

4.2 Local proxy

CC Switch ships a local proxy server that provides:

Hot-switching — change Provider without restarting the CLI
Auto-failover — fall back to a secondary Provider if the current one is down
Circuit breaking — stop sending requests when a Provider keeps failing

Configure GravitexAI main + GravitexAI backup key as failover targets for maximum availability.

4.3 Backups

Auto-backup keeps the last 10 versions
Import / export full configs
Cloud sync via Dropbox, OneDrive, iCloud, WebDAV

5. FAQ

Which OSes are supported?

Windows 10+, macOS 10.15 (Catalina)+, and major Linux distros (Ubuntu 22.04+, Debian 11+, Fedora 34+, Arch Linux).

Claude Code can't connect after configuration?

Check in order:

API key starts with sk- and has no extra whitespace / newlines
Base URL for Claude Code is https://api.gravitex.ai (no /v1)
Account has sufficient balance — see the GravitexAI console
CC Switch actually wrote the config to ~/.claude/
Restart the terminal — env-var changes need a new session

OpenCode errors out with gpt-5.1-codex?

Codex-series models only support the Responses API. Add "apiCompatibility": "responses" for that model in opencode.jsonc — see the OpenCode guide for details.

How do I migrate from manual configs?

On first launch, CC Switch scans ~/.claude/, ~/.codex/, ~/.config/opencode/ and similar paths and imports existing setups automatically. You can also use Import config for backup files.

What's the difference between standard and Thinking models?

Thinking models force a chain-of-thought before answering — great for complex reasoning and architectural design. Standard models reply faster and suit everyday coding. GravitexAI variants ending in -thinking are the reasoning versions.

Does CC Switch itself cost anything?

No. CC Switch is fully open-source (MIT). Only the API calls cost money — billed at GravitexAI’s per-token rates.

6. Best Practices

Pro tips:

One Provider to rule them all — point every CLI at GravitexAI to avoid juggling multiple keys/URLs.
Use hot-switching — flip between claude-opus-4-7 / claude-sonnet-4-6 / claude-haiku-4-5-20251001 based on task complexity.
Enable auto-failover — pair a primary and backup Provider (or two keys) for continuity.
Back up regularly — turn on cloud sync so reinstalls don’t wipe your config.
Pair with MCP — manage MCP servers centrally so all CLI tools share the same external capabilities.

7. References

CC Switch on GitHub

Source, issues and latest releases

Claude Code guide

Detailed Claude Code setup

GravitexAI console

Manage keys and usage

Model catalog

Browse 100+ mainstream AI models

Documentation Index

​1. Overview

One-click switching

Multi-model aggregation

Usage tracking

Smart failover

​2. Core Features

​2.1 Provider management

​2.2 MCP server management

​2.3 More

​3. Quick Start

​Step 1 — Install CC Switch

​Step 2 — Get a GravitexAI key

​Step 3 — Configure GravitexAI in CC Switch

​Step 4 — Add models

​Step 5 — Switch and launch a CLI

​4. Usage Guide

​4.1 Manage multiple CLI tools

​4.2 Local proxy

​4.3 Backups

​5. FAQ

​6. Best Practices

​7. References

CC Switch on GitHub

Claude Code guide

GravitexAI console

Model catalog

1. Overview

2. Core Features

2.1 Provider management

2.2 MCP server management

2.3 More

3. Quick Start

Step 1 — Install CC Switch

Step 2 — Get a GravitexAI key

Step 3 — Configure GravitexAI in CC Switch

Step 4 — Add models

Step 5 — Switch and launch a CLI

4. Usage Guide

4.1 Manage multiple CLI tools

4.2 Local proxy

4.3 Backups

5. FAQ

6. Best Practices

7. References