CC-Switch TUI

Command-Line Management Tool for Claude Code, Codex, Gemini, OpenCode & OpenClaw

Unified management for Claude Code, Codex, Gemini, OpenCode, and OpenClaw provider configurations, plus app-specific support for MCP servers, skills, prompts, local proxy routes, and environment checks.

English | 中文

---

📖 About

This project is a TUI fork whose upstream repository is SaladDay/cc-switch-cli.

🔄 The WebDAV sync feature is fully compatible with the upstream project.

Credits: Original architecture and core functionality from farion1231/cc-switch

Changelog: docs/cc-switch-tui/CHANGELOG.md

---

📸 Screenshots

🚀 Quick Start

Interactive Mode (Recommended)

cc-switch

🤩 Follow on-screen menus to explore features.

Command-Line Mode

cc-switch-tui provider list              # List providers
cc-switch-tui provider switch <id>       # Switch provider
cc-switch-tui provider export <id>       # Export a Claude provider to a standalone settings file
cc-switch-tui provider stream-check <id> # Check provider stream health
cc-switch-tui config webdav show         # Inspect WebDAV sync settings
cc-switch-tui env tools                  # Check local CLI tools
cc-switch-tui mcp sync                   # Sync MCP servers
cc-switch-tui proxy show                 # Inspect proxy routes and status

# Use the global `--app` flag to target specific applications:
cc-switch-tui --app claude provider list    # Manage Claude providers
cc-switch-tui --app codex mcp sync          # Sync Codex MCP servers
cc-switch-tui --app gemini prompts list     # List Gemini prompts
cc-switch-tui --app openclaw provider list  # Manage OpenClaw providers

# Supported apps: `claude` (default), `codex`, `gemini`, `opencode`, `openclaw`

See the "Features" section for full command list.

---

📥 Installation

Method 1: Quick Install (macOS / Linux)

Windows users: see Manual Installation below.

curl -fsSL https://github.com/handy-sun/cc-switch-tui/releases/latest/download/install.sh | bash

This installs to ~/.local/bin. Set CC_SWITCH_INSTALL_DIR to change the target directory.

• If the target already exists, the installer prompts in TTY and refuses to overwrite in non-interactive shells unless CC_SWITCH_FORCE=1 is set.
• On Linux, set CC_SWITCH_LINUX_LIBC=glibc if you need the glibc build.

macOS

# Download Universal Binary (recommended, supports Apple Silicon + Intel)
VERSION="$(curl -fsSL https://github.com/handy-sun/cc-switch-tui/releases/latest/download/latest.json | sed -nE 's/^[[:space:]]*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/p' | head -n 1)"
curl -LO "https://github.com/handy-sun/cc-switch-tui/releases/download/${VERSION}/cc-switch-tui-${VERSION}-darwin-universal.tar.gz"

# Extract
tar -xzf "cc-switch-tui-${VERSION}-darwin-universal.tar.gz"

# Add execute permission
chmod +x cc-switch-tui

# Move to PATH
sudo mv cc-switch-tui /usr/local/bin/

# If you encounter "cannot be verified" warning
xattr -cr /usr/local/bin/cc-switch-tui

Linux (x64)

# Download
VERSION="$(curl -fsSL https://github.com/handy-sun/cc-switch-tui/releases/latest/download/latest.json | sed -nE 's/^[[:space:]]*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/p' | head -n 1)"
curl -LO "https://github.com/handy-sun/cc-switch-tui/releases/download/${VERSION}/cc-switch-tui-${VERSION}-linux-x64-musl.tar.gz"

# Extract
tar -xzf "cc-switch-tui-${VERSION}-linux-x64-musl.tar.gz"

# Add execute permission
chmod +x cc-switch-tui

# Move to PATH
sudo mv cc-switch-tui /usr/local/bin/

Linux (ARM64)

# For Raspberry Pi or ARM servers
VERSION="$(curl -fsSL https://github.com/handy-sun/cc-switch-tui/releases/latest/download/latest.json | sed -nE 's/^[[:space:]]*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/p' | head -n 1)"
curl -LO "https://github.com/handy-sun/cc-switch-tui/releases/download/${VERSION}/cc-switch-tui-${VERSION}-linux-arm64-musl.tar.gz"
tar -xzf "cc-switch-tui-${VERSION}-linux-arm64-musl.tar.gz"
chmod +x cc-switch-tui
sudo mv cc-switch-tui /usr/local/bin/

Windows

# Download the zip file
# https://github.com/handy-sun/cc-switch-tui/releases/download/vX.Y.Z/cc-switch-tui-vX.Y.Z-windows-x64.zip

# After extracting, move cc-switch-tui.exe to a PATH directory, e.g.:
move cc-switch-tui.exe C:\Windows\System32\

# Or run directly
.\cc-switch-tui.exe

Method 2: Nix Flake

Use the package from this repository in another flake:

{
  inputs.cc-switch-tui = {
    url = "github:handy-sun/cc-switch-tui";
    inputs.nixpkgs.follows = "nixpkgs";
  };
}

inputs.nixpkgs.follows = "nixpkgs" is recommended for normal NixOS or Home Manager setups. The package is built with pkgs.rustPlatform.buildRustPackage, so following your top-level nixpkgs means the Rust compiler, Cargo, linker inputs, and system libraries come from the same nixpkgs revision as the rest of your system.

If you omit follows, this project uses the nixpkgs revision pinned in its own flake.lock, which can be useful when you want to reproduce the upstream build environment exactly. In either case, Rust crate dependency versions still come from src-tauri/Cargo.lock; follows changes the Nix toolchain and package set, not the locked Cargo dependency graph.

If a build only fails with follows enabled, try removing it to check whether the issue is caused by a nixpkgs version difference.

Method 3: Build from Source

Prerequisites:

• Rust 1.94+ (install via rustup)

Build:

git clone https://github.com/handy-sun/cc-switch-tui.git
cd cc-switch-tui/src-tauri
cargo build --release

# Binary location: ./target/release/cc-switch

Install to System:

# macOS/Linux
sudo cp target/release/cc-switch-tui /usr/local/bin/

# Windows
copy target\release\cc-switch-tui.exe C:\Windows\System32\

---

✨ Features

🔌 Provider Management

Manage API configurations for Claude Code, Codex, Gemini, OpenCode, and OpenClaw.

Features: One-click switching, standalone Claude settings export, multi-endpoint support, API key management, remote model discovery, and per-app diagnostics such as speed testing or stream health checks where supported.

cc-switch-tui provider list              # List all providers
cc-switch-tui provider current           # Show current provider
cc-switch-tui provider switch <id>       # Switch provider
cc-switch-tui provider add               # Add new provider
cc-switch-tui provider edit <id>         # Edit existing provider
cc-switch-tui provider duplicate <id>    # Duplicate a provider
cc-switch-tui provider delete <id>       # Delete provider
cc-switch-tui provider export <id>       # Export to ./.claude/settings.local.json for Claude auto-load
cc-switch-tui provider speedtest <id>    # Test API latency
cc-switch-tui provider stream-check <id> # Run stream health check
cc-switch-tui provider fetch-models <id> # Fetch remote model list
cc-switch-tui provider export <id> --output ~/.claude/settings-demo.json # Custom settings file path

🛠️ MCP Server Management

Manage Model Context Protocol servers across Claude, Codex, Gemini, and OpenCode.

Features: Unified management, multi-app support, three transport types (stdio/http/sse), automatic sync, and live-config adapters for TOML and JSON targets.

cc-switch-tui mcp list                   # List all MCP servers
cc-switch-tui mcp add                    # Add new MCP server (interactive)
cc-switch-tui mcp edit <id>              # Edit MCP server
cc-switch-tui mcp delete <id>            # Delete MCP server
cc-switch-tui mcp enable <id> --app claude   # Enable for specific app
cc-switch-tui mcp disable <id> --app claude  # Disable for specific app
cc-switch-tui mcp validate <command>     # Validate command in PATH
cc-switch-tui mcp sync                   # Sync to live files
cc-switch-tui mcp import --app claude    # Import from live config

💬 Prompts Management

Manage system prompt presets for AI coding assistants.

Cross-app support: Claude (CLAUDE.md), Codex (AGENTS.md), Gemini (GEMINI.md), OpenCode (AGENTS.md), OpenClaw (AGENTS.md).

cc-switch-tui prompts list               # List prompt presets
cc-switch-tui prompts current            # Show current active prompt
cc-switch-tui prompts activate <id>      # Activate prompt
cc-switch-tui prompts deactivate         # Deactivate current active prompt
cc-switch-tui prompts create [name]      # Create a prompt preset, optionally naming it up front
cc-switch-tui prompts rename <id> [name] # Rename prompt preset, interactive if name is omitted
cc-switch-tui prompts edit <id>          # Edit prompt preset
cc-switch-tui prompts show <id>          # Display full content
cc-switch-tui prompts delete <id>        # Delete prompt

🎯 Skills Management

Manage and extend Claude Code/Codex/Gemini/OpenCode capabilities with community skills.

Features: SSOT-based skills store, multi-app enable/disable, sync to app directories, unmanaged scan/import, repo discovery.

cc-switch-tui skills list                # List installed skills
cc-switch-tui skills discover <query>      # Discover available skills (alias: search)
cc-switch-tui skills install <name>      # Install a skill
cc-switch-tui skills uninstall <name>    # Uninstall a skill
cc-switch-tui skills enable <name>       # Enable for current app (--app)
cc-switch-tui skills disable <name>      # Disable for current app (--app)
cc-switch-tui skills info <name>         # Show skill information
cc-switch-tui skills sync                # Sync enabled skills to app dirs
cc-switch-tui skills sync-method [m]     # Show/set sync method (auto|symlink|copy)
cc-switch-tui skills scan-unmanaged      # Scan unmanaged skills in app dirs
cc-switch-tui skills import-from-apps    # Import unmanaged skills into SSOT
cc-switch-tui skills repos list          # List skill repositories
cc-switch-tui skills repos add <repo>    # Add repo (owner/name[@branch] or GitHub URL)
cc-switch-tui skills repos remove <repo> # Remove repo (owner/name or GitHub URL)
cc-switch-tui skills repos enable <repo> # Enable repo without changing branch
cc-switch-tui skills repos disable <repo> # Disable repo without changing branch

⚙️ Configuration Management

Manage configuration backups, imports, and exports.

Features: Custom backup naming, interactive backup selection, automatic rotation (keep 10), import/export, common snippets, WebDAV sync.

cc-switch-tui config show                # Display configuration
cc-switch-tui config path                # Show config file paths
cc-switch-tui config validate            # Validate config file

# Common snippet (shared settings across providers)
# Tries to refresh live config when applicable (`--apply` is kept only as a compatibility flag)
cc-switch-tui --app claude config common show
cc-switch-tui --app claude config common set --snippet '{"env":{"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":1},"includeCoAuthoredBy":false}'
cc-switch-tui --app claude config common clear

# Backup
cc-switch-tui config backup              # Create backup (auto-named)
cc-switch-tui config backup --name my-backup  # Create backup with custom name

# Restore
cc-switch-tui config restore             # Interactive: select from backup list
cc-switch-tui config restore --backup <id>    # Restore specific backup by ID
cc-switch-tui config restore --file <path>    # Restore from external file

# Import/Export
cc-switch-tui config export <path>       # Export to external file
cc-switch-tui config import <path>       # Import from external file

# WebDAV sync
cc-switch-tui config webdav show
cc-switch-tui config webdav set --base-url <url> --username <user> --password <password> --enable
cc-switch-tui config webdav jianguoyun --username <user> --password <password>
cc-switch-tui config webdav check-connection
cc-switch-tui config webdav upload
cc-switch-tui config webdav download
cc-switch-tui config webdav migrate-v1-to-v2

cc-switch-tui config reset               # Reset to default configuration

🌉 Proxy Management

Inspect and control the local multi-app proxy used by supported apps.

Features: Persisted enable/disable switch, current route inspection, dashboard telemetry, and foreground serve mode for debugging.

cc-switch-tui proxy show                 # Show proxy configuration and routes
cc-switch-tui proxy enable               # Enable the persisted proxy switch
cc-switch-tui proxy disable              # Disable the persisted proxy switch
cc-switch-tui proxy serve                # Run the proxy in foreground

🧪 Environment & Local Tools

Inspect environment conflicts and whether required local CLIs are installed.

cc-switch-tui env check                  # Check environment conflicts
cc-switch-tui env list                   # List relevant environment variables
cc-switch-tui env tools                  # Check Claude/Codex/Gemini/OpenCode CLIs

🌐 Multi-language Support

Interactive mode supports English and Chinese, language settings are automatically saved.

• Default language: English
• Go to ⚙️ Settings menu to switch language

🔧 Utilities

Shell completions, environment management, and other utilities.

# Shell completions
cc-switch-tui completions install --activate   # Recommended: install + activate for bash/zsh
cc-switch-tui completions install              # Conservative: install only, no rc edits
cc-switch-tui completions status               # Inspect managed completion status
cc-switch-tui completions uninstall            # Remove managed completion assets
cc-switch-tui completions bash                 # Compatibility raw generator path
cc-switch-tui completions fish                 # Raw generation still works for non-managed shells

# Environment management
cc-switch-tui env check                  # Check for environment conflicts
cc-switch-tui env list                   # List environment variables

# Self-update
cc-switch-tui update                     # Update to latest release
cc-switch-tui update --version vX.Y.Z    # Update to a specific version

Automated install/activation currently targets bash and zsh only. Other shells remain available through the raw generator path, for example cc-switch-tui completions fish.

---

🏗️ Architecture

Core Design

• SQLite-backed state: Core data lives in ~/.cc-switch-tui/cc-switch.db by default (or under $CC_SWITCH_TUI_CONFIG_DIR/ when set); legacy config.json is kept only for older import and migration paths
• Skills SSOT: Skill source files live in ~/.cc-switch-tui/skills/ by default (or under $CC_SWITCH_TUI_CONFIG_DIR/skills/ when set), while install state and app enablement stay in the database
• Safe Live Sync (Default): Skip writing live files for apps that haven't been initialized yet (prevents creating ~/.claude, ~/.codex, ~/.gemini, ~/.config/opencode, or ~/.openclaw unexpectedly)
• Atomic Writes: Temp file + rename pattern prevents corruption
• Service Layer Reuse: 100% reused from original GUI version
• Concurrency Safe: RwLock with scoped guards

Configuration Files

CC-Switch Storage (default: ~/.cc-switch-tui, override: CC_SWITCH_TUI_CONFIG_DIR):

• ~/.cc-switch-tui/cc-switch.db - Main database for providers, MCP, prompts, and app state
• ~/.cc-switch-tui/settings.json - Settings
• ~/.cc-switch-tui/skills/ - Installed skill sources (SSOT)
• ~/.cc-switch-tui/backups/ - Auto-rotation (keep 10)
• ~/.cc-switch-tui/config.json - Legacy JSON kept for compatibility and import flows

When CC_SWITCH_TUI_CONFIG_DIR is set, CC-Switch uses that directory as its config root; existing data under ~/.cc-switch-tui is not migrated automatically.

Live Configs:

• Claude: ~/.claude/settings.json (provider/common config), ~/.claude.json (MCP), ~/.claude/CLAUDE.md (prompts)
• Codex: ~/.codex/auth.json (auth state), ~/.codex/config.toml (provider/common config + MCP), ~/.codex/AGENTS.md (prompts)
• Gemini: ~/.gemini/.env (provider env), ~/.gemini/settings.json (settings + MCP), ~/.gemini/GEMINI.md (prompts)
• OpenCode: ~/.config/opencode/opencode.json (providers + MCP + runtime config), ~/.config/opencode/AGENTS.md (prompts)
• OpenClaw: ~/.openclaw/openclaw.json (providers + env/tools/agents defaults), ~/.openclaw/AGENTS.md (prompts)

---

❓ FAQ (Frequently Asked Questions)

First, make sure the target CLI has been initialized at least once (i.e. its config directory exists). CC-Switch may skip live sync for uninitialized apps; you will see a warning. Run the target CLI once (e.g. claude --help, codex --help, gemini --help, opencode --help, openclaw --help), then switch again.

This is usually caused by environment variable conflicts. If you have API keys set in system environment variables (like ANTHROPIC_API_KEY, OPENAI_API_KEY), they will override CC-Switch's configuration.

Solution:

1. Check for conflicts:

   cc-switch-tui env check --app claude
   

2. List all related environment variables:

   cc-switch-tui env list --app claude
   

3. If conflicts are found, manually remove them:

   • macOS/Linux: Edit your shell config file (~/.bashrc, ~/.zshrc, etc.)

     # Find and delete the line with the environment variable
     nano ~/.zshrc
     # Or use your preferred text editor: vim, code, etc.
     

   • Windows: Open System Properties → Environment Variables and delete the conflicting variables

4. Restart your terminal for changes to take effect.

CC-Switch currently supports five AI coding assistants:

• Claude Code (--app claude, default)
• Codex (--app codex)
• Gemini (--app gemini)
• OpenCode (--app opencode)
• OpenClaw (--app openclaw)

Use the global --app flag to specify which app to manage:

cc-switch-tui --app codex provider list

Please open an issue on our GitHub Issues page with:

• Detailed description of the problem or feature request
• Steps to reproduce (for bugs)
• Your system information (OS, version)
• Relevant logs or error messages

---

🛠️ Development

Requirements

• Rust: 1.94+ (rustup)
• Cargo: Bundled with Rust

Commands

cd src-tauri

cargo run                            # Development mode
cargo run -- provider list           # Run specific command
cargo build --release                # Build release

cargo fmt                            # Format code
cargo clippy                         # Lint code
cargo test                           # Run tests

Code Structure

src-tauri/src/
├── cli/
│   ├── commands/          # CLI subcommands (provider, mcp, prompts, skills, proxy, env, ...)
│   ├── tui/               # Interactive TUI mode (ratatui)
│   ├── interactive/       # Interactive entrypoint / TTY gate
│   └── ui/                # UI utilities (tables, colors)
├── services/              # Business logic (provider, mcp, prompt, webdav, ...)
├── database/              # SQLite storage, migrations, backup
├── main.rs                # CLI entry point
└── ...                    # App-specific configs, proxy, error handling

🤝 Contributing

Contributions welcome! This fork focuses on CLI functionality.

Before submitting PRs:

• ✅ Pass format check: cargo fmt --check
• ✅ Pass linter: cargo clippy
• ✅ Pass tests: cargo test
• 💡 Open an issue for discussion first

---

📜 License

• MIT © Original Author: Jason Young
• CLI Fork Maintainer: saladday