ccsctx 0.1.0

Fast provider switcher for cc-switch
Documentation

ccsctx

一个面向 cc-switch 的轻量命令行切换工具。

目标是用最短命令在终端里切换 Claude/Codex/Gemini 的 provider，并支持可选 fzf 交互选择。

功能

  • 支持应用：claude、codex、gemini
  • 支持通过 provider ID 或展示名切换
  • 无参数时列出 provider，并用 * 标记当前项
  • 支持别名命令：claudectx、codexctx、geminictx
  • 支持 CCSCTX_FZF=1 启用 fzf 选择模式
  • 切换后同步：
    • providers.is_current（SQLite）
    • ~/.cc-switch/settings.json 的 currentProvider*
    • 对应 app 的 live 配置文件

当前状态

  • claude：支持
    • 优先读 SQLite（~/.cc-switch/cc-switch.db）
    • 若 DB 不存在，回退到 ~/.cc-switch/config.json
  • codex：支持（依赖 SQLite）
  • gemini：支持（依赖 SQLite）
  • opencode：当前不支持（--app opencode 会报错）

安装

方式 1：本地构建

cargo build --release

可执行文件在：

  • target/release/ccsctx
  • target/release/claudectx
  • target/release/codexctx
  • target/release/geminictx

方式 2：开发调试运行

cargo run --bin ccsctx -- --help

用法

ccsctx [--app <app>] [provider]

参数：

  • provider：可选。为空时进入“列出 provider”模式。
  • --app <app>：claude | codex | gemini。
  • --verbose：切换时输出详细写入摘要（写了哪些文件、跳过了哪些字段、warning）。

常见示例

列出 Claude provider（默认 app）：

ccsctx

切换 Claude：

ccsctx "Claude Official"
# 或
ccsctx p2

列出 Codex：

ccsctx --app codex
# 或
codexctx

切换 Gemini：

ccsctx --app gemini "MiniMax Gemini"
# 或
geminictx gm2

查看详细切换信息：

ccsctx --app codex cx2 --verbose

fzf 模式

开启条件：

  1. 环境变量 CCSCTX_FZF=1
  2. 本机已安装 fzf

示例：

CCSCTX_FZF=1 ccsctx --app claude

说明：

  • 开启后，无 provider 参数时会进入 fzf 选择。
  • 如果开启了 CCSCTX_FZF=1 但系统找不到 fzf，会自动回退到普通列表模式并打印 warning。

live 配置写入路径

默认路径：

  • Claude: ~/.claude/settings.json
  • Codex:
    • ~/.codex/auth.json
    • ~/.codex/config.toml
  • Gemini:
    • ~/.gemini/settings.json
    • ~/.gemini/.env

环境变量

通用

  • CCSCTX_DB：覆盖 cc-switch SQLite 路径（默认 ~/.cc-switch/cc-switch.db）
  • CCSCTX_SETTINGS：覆盖 cc-switch settings.json 路径
  • CCSCTX_FZF=1：启用 fzf 模式

Claude

  • CCSCTX_CONFIG：覆盖 config.json 路径（仅 DB 不存在时使用）
  • CCSCTX_CLAUDE_LIVE：覆盖 Claude live 配置路径

Codex

  • CCSCTX_CODEX_DIR：覆盖 Codex 目录（默认 ~/.codex）
  • CCSCTX_CODEX_AUTH：覆盖 auth 文件路径
  • CCSCTX_CODEX_CONFIG：覆盖 config 文件路径

Gemini

  • CCSCTX_GEMINI_DIR：覆盖 Gemini 目录（默认 ~/.gemini）
  • CCSCTX_GEMINI_SETTINGS：覆盖 settings 文件路径
  • CCSCTX_GEMINI_ENV：覆盖 .env 文件路径

错误与退出码

  • 成功切换：退出码 0
  • 已是当前 provider：退出码 0（输出 already current）
  • 业务错误（provider 不存在、配置异常等）：退出码 1
  • 参数错误（如 --app opencode）：退出码 2

开发

运行测试：

cargo test -- --nocapture

运行静态检查：

cargo clippy --all-targets -- -D warnings

格式化：

cargo fmt

说明

  • 本项目聚焦“快速切换 provider”场景，不覆盖 cc-switch 全功能。
  • cc-switch 页面当前不会自动感知外部 CLI 的变更；重启后可读取到最新状态。