# cctui

**Repository Path**: aixinyin/cctui

## Basic Information

- **Project Name**: cctui
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-14
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CC Switch TUI

`CC Switch TUI` 是一个终端界面工具，用来管理并切换 `Claude`、`Codex`、`Gemini` 的多套供应商配置。

它适合以下场景：

- 在官方接口、代理接口、公司内网网关之间快速切换
- 为不同应用分别维护多套 `Base URL`、`API Key`、`Model`
- 用可视化 TUI 替代手动编辑多个配置文件

## 功能特性

- 支持 `Claude`、`Codex`、`Gemini`、`Pi` 四类应用/Agent
- 支持 **全局供应商**：一次添加，自动同步到 Claude/Codex/Gemini/Pi，再到各分组里切换启用
- 使用 SQLite 保存供应商配置，数据默认位于 `~/.cc-switch/`
- 首次启动时，如果某个应用还没有保存的供应商，会尝试导入当前 live 配置
- 切换前会先读取当前 live 配置并回写数据库，尽量保留你在外部手动改过的内容
- 支持新增、编辑、删除、切换供应商
- `Codex` 额外支持配置 `Reasoning Effort`

## 管理的配置文件

程序会读取并写入这些 live 配置文件：

- `Claude`：`~/.claude/settings.json`
- `Claude` 兼容旧文件：`~/.claude/claude.json`
- `Codex`：`~/.codex/auth.json`
- `Codex`：`~/.codex/config.toml`
- `Gemini`：`~/.gemini/.env`
- `Gemini`：`~/.gemini/settings.json`
- `Pi`：`~/.pi/agent/models.json`
- `Pi`：`~/.pi/agent/auth.json`
- `Pi`：`~/.pi/agent/settings.json`

程序自己的本地数据默认保存在：

- `~/.cc-switch/cc-switch.db`
- `~/.cc-switch/settings.json`

## 环境要求

- `Go 1.26+`
- 可以访问对应应用的本地配置目录
- 终端支持 TUI/Alt Screen

## 构建与运行

### 直接运行

```bash
go run .
```

### 构建二进制

```bash
go build -o cctui .
./cctui
```

### 常用命令行参数

```bash
cctui                     # 启动 TUI
cctui update              # 检查并更新
cctui update -y           # 更新（免确认）
cctui check-update        # 仅检查新版本
cctui uninstall           # 卸载程序
cctui uninstall --purge   # 卸载并删除 ~/.cc-switch
cctui version             # 版本号
cctui help                # 帮助
```

## AUR 自动发布

仓库内置了 GitHub Actions workflow：当你给 GitHub 仓库 push 一个 tag 时，会自动更新 AUR 仓库：

- AUR 仓库地址：`aur@aur.archlinux.org:cctui.git`
- Workflow 文件：`.github/workflows/publish-aur.yml`
- 生成脚本：`scripts/update-aur.sh`

### GitHub Secret

你需要在 GitHub 仓库里配置一个 secret：

- `AUR_SSH_PRIVATE_KEY`

它应该对应一个有权限 push 到 `aur@aur.archlinux.org:cctui.git` 的 SSH 私钥。

### 本地测试 AUR 生成

你已经在本地准备了测试仓库 `~/test/cctui`，可以这样测试：

```bash
./scripts/update-aur.sh \
  --tag v0.0.0 \
  --aur-dir ~/test/cctui \
  --archive-url https://github.com/manateelazycat/cctui/archive/refs/heads/main.tar.gz \
  --archive-dir-name cctui-main \
  --validate
```

这条命令会：

- 生成 `PKGBUILD`
- 生成 `.SRCINFO`
- 用 `makepkg --printsrcinfo` 校验 `.SRCINFO` 是否正确

## 使用方式

启动后会看到按应用分组的供应商列表：

- `Enter`：将当前选中的供应商设为正在使用（全局供应商不会直接切换）
- `a`：新增供应商
- `e`：编辑供应商
- `d`：删除供应商
- `u`：检查更新；发现新版本后可确认自动下载并替换
- `t`：对当前供应商测速
- `0/1/2/3/4`：跳到 全局 / Claude / Codex / Gemini / Pi

表单里多项枚举字段（Reasoning Effort/Summary、Verbosity、Service Tier、Wire API、API Type、Reasoning、compat 开关等）支持 **Enter 弹出选项** 或 **←/→ 切换**。
- `↑/↓` 或 `j/k`：移动光标

### 全局供应商

列表顶部是 **全局** 分组。在这里新增供应商后，会自动在 Claude、Codex、Gemini、Pi 中各创建一份同名配置，但不会自动切换 live。

你再到对应 CLI 分组里选中那份配置，按 `Enter` 才会写到本地配置文件并生效。

编辑全局供应商会同步更新各 CLI/Agent 中的关联副本；删除全局供应商会尽量删除这些副本（若某 CLI 正在使用且还有其他供应商，则该副本会保留）。
- `1/2/3`：快速跳转到 `Claude` / `Codex` / `Gemini`
- `g/G`：跳到顶部 / 底部
- `Esc`：退出

表单模式下：

- `Tab` / `Shift+Tab`：切换字段
- `Enter`：下一项，最后一项时保存
- `Ctrl+S`：保存
- `Esc`：取消并返回

## 供应商字段说明

通用字段：

- `名称`：供应商显示名称
- `Base URL`：接口地址；留空通常表示沿用官方登录或 OAuth 语义
- `API Key`：接口密钥；留空时会尽量保留登录态语义
- `Model`：默认模型
- `Website`：可选，供应商官网
- `Notes`：可选，备注

`Claude` 扩展字段：

- `Reasoning Model`：写入 `ANTHROPIC_REASONING_MODEL`
- `Haiku/Fast Model`：写入 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 与 `ANTHROPIC_SMALL_FAST_MODEL`；留空则与主 Model 相同

`Codex` 扩展字段：

- `Reasoning Effort`：`minimal / low / medium / high / xhigh`
- `Reasoning Summary`：`auto / concise / detailed / none`
- `Verbosity`：`low / medium / high`
- `Service Tier`：`default / priority / flex / fast`
- `Wire API`：`responses`（官方默认）或 `chat`（仅支持 Chat Completions 的中转）
- `Context Window`：`model_context_window`

`Pi` 扩展字段：

- `API Type`：`openai-completions` / `openai-responses` / `anthropic-messages` / `google-generative-ai`
- `Context Window`：默认 `128000`
- `Max Tokens`：`models[].maxTokens`
- `Reasoning`：是否按推理模型处理（默认 `true`）
- `Max Tokens Field` / `Supports Developer Role` / `Supports Reasoning Effort` / `Supports Usage In Streaming`：写入 provider `compat`

全局供应商表单是字段并集：保存后同步到各 CLI，目标端只消费自己认识的字段。

## 默认行为

### 首次启动导入

如果某个应用在数据库里还没有供应商，程序会尝试读取该应用当前正在使用的 live 配置，并自动导入一条记录，例如 `Imported Claude`。

### 切换时同步

切换到新供应商前，程序会先尝试读取当前 live 配置，并回写到当前供应商记录中；随后再把目标供应商写入 live 配置文件。

## 高级配置

可以在 `~/.cc-switch/settings.json` 中覆盖默认配置目录：

```json
{
  "claudeConfigDir": "/path/to/.claude",
  "codexConfigDir": "/path/to/.codex",
  "geminiConfigDir": "/path/to/.gemini"
}
```

其中“当前供应商”相关字段也会保存在这个文件里，通常不建议手动修改。

## 适用场景

- 在官方和第三方中转之间快速切换
- 分离工作环境与个人环境配置
- 为不同模型服务保留独立的历史配置
- 用统一入口管理多个 AI CLI / 桌面工具的连接参数