https://github.com/guyskk/claude-code-supervisor
Auto-review and iterate until quality work is delivered - a better alternative to ralph-claude-code. Switch between multiple Claude Code providers (Kimi, GLM, MiniMax, etc.) with a single command.
https://github.com/guyskk/claude-code-supervisor
ai ai-agents ai-development-tools ai-tools claude-code claude-code-cli claude-code-plugin codex developer-tools glm kimi-k2 minimax opencode provider-management zhipuai
Last synced: 8 days ago
JSON representation
Auto-review and iterate until quality work is delivered - a better alternative to ralph-claude-code. Switch between multiple Claude Code providers (Kimi, GLM, MiniMax, etc.) with a single command.
- Host: GitHub
- URL: https://github.com/guyskk/claude-code-supervisor
- Owner: guyskk
- License: mit
- Created: 2025-12-27T14:38:47.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-26T04:03:10.000Z (16 days ago)
- Last Synced: 2026-03-27T00:38:05.919Z (15 days ago)
- Topics: ai, ai-agents, ai-development-tools, ai-tools, claude-code, claude-code-cli, claude-code-plugin, codex, developer-tools, glm, kimi-k2, minimax, opencode, provider-management, zhipuai
- Language: Go
- Homepage:
- Size: 688 KB
- Stars: 55
- Watchers: 2
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README-CN.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# ccc - Claude Code 监督器
[English](README.md) | [中文文档](README-CN.md)
## 为什么选择 ccc？
`ccc` 是一个增强 Claude Code 的命令行工具，提供两大核心功能：
1. **Supervisor 模式**: ⭐ 自动任务审查，确保高质量、可交付的成果
2. **无缝提供商切换**: 一条命令在 Kimi、GLM、MiniMax 等提供商之间切换
**优于 `ralph-claude-code`**：
- Supervisor 模式使用 Stop Hook 触发的审查机制配合严格的六步框架，显著提高任务完成度和质量。
- 与 ralph 基于信号的退出检测不同，ccc 的 Supervisor 会 Fork 完整的会话上下文来评估实际工作质量。
- 这有效防止了 AI 声称"完成"但结果质量差、仍有很多问题的虚假完成情况。
## 快速开始
### 1. 安装
#### 选项 A：一键安装（Linux / macOS）
```bash
OS=$(uname -s | tr '[:upper:]' '[:lower:]'); ARCH=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/'); curl -LO "https://github.com/guyskk/claude-code-supervisor/releases/latest/download/ccc-${OS}-${ARCH}" && sudo install -m 755 "ccc-${OS}-${ARCH}" /usr/local/bin/ccc && rm "ccc-${OS}-${ARCH}" && ccc --version
```
#### 选项 B：从 [Releases](https://github.com/guyskk/claude-code-supervisor/releases) 下载
下载适合你平台的二进制文件（`ccc-darwin-arm64`、`ccc-linux-amd64` 等）并安装到 `/usr/local/bin/`。
### 2. 配置
如果你已有 `~/.claude/settings.json`，首次运行 `ccc` 时会提示迁移并自动生成 ccc 配置 `~/.claude/ccc.json`。
你也可以自行创建配置文件，示例如下：
```json
{
"settings": {
"permissions": {
"defaultMode": "bypassPermissions"
}
},
"providers": {
"glm": {
"env": {
"ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
"ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY_HERE",
"ANTHROPIC_MODEL": "glm-4.7"
}
},
"kimi": {
"env": {
"ANTHROPIC_BASE_URL": "https://api.moonshot.cn/anthropic",
"ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY_HERE",
"ANTHROPIC_MODEL": "kimi-k2-thinking"
}
}
}
}
```
> **安全警告**：`bypassPermissions` 允许 Claude Code 无需确认即可执行工具。仅在受信任的环境中使用。
### 3. 使用
```bash
# 查看帮助信息
ccc --help
# 切换到指定提供商并运行 Claude Code
ccc glm
# 使用当前提供商
ccc
# 传递任何 Claude Code 参数
ccc glm -p
```
### 4. 验证（可选）
验证提供商配置：
```bash
# 验证当前提供商
ccc validate
# 验证所有提供商
ccc validate --all
```
## 配置合并策略
**你的配置永远不会丢失！** ccc 遵循以下原则合并配置：
- **优先级**：用户的 `settings.json` 配置具有最高优先级
- **提供商配置**：ccc.json 中的提供商特定配置覆盖基础设置
- **基础设置**：ccc.json 中的 `settings` 字段作为共享模板
#### 保留的内容
- ✅ 用户安装的插件（`enabledPlugins`）- 不会被覆盖
- ✅ 手动编辑的 `settings.json`（权限、沙箱等）- 完全保留
- ✅ 用户配置的其他 hooks（PreToolUse、SessionStart 等）- 被尊重
- ✅ 用户在 `settings.json` 中手动设置的环境变量 - 不会被删除（除了冲突，见下文）
#### 管理的内容
- 🤖 Supervisor Stop hook - 自动添加/确保
- 🧹 环境变量冲突 - `ANTHROPIC_*`、`CLAUDE_*` 和提供商 env 键从 `settings.json` 中移除以避免歧义
- ⚙️ Hook 执行标志 - `disableAllHooks` 和 `allowManagedHooksOnly` 设置为 `false` 以确保 hooks 能正常工作
#### 工作原理
当你运行 `ccc` 时：
1. 读取现有的 `settings.json`（如果存在）
2. 按优先级合并配置：`用户 > 提供商 > 基础`
3. 提供商的环境变量通过命令行传递（不写入 `settings.json`）
4. 添加 Supervisor Stop hook（如果需要）同时保留用户的其他 hooks
这样可以确保你的手动配置永远不会丢失！
## Supervisor 模式（推荐）
Supervisor 模式是 `ccc` 最有价值的特性。它会在 Agent 每次停止后自动审查工作质量，如果未完成则提供反馈让 Agent 继续执行。
### 如何使用
1. 启动 `ccc`，与 Agent 沟通确认需求和方案：
```bash
ccc
```
2. 使用斜杠命令启用 Supervisor 模式：
```text
/supervisor 好，开始执行
```
3. Agent 会执行任务，Supervisor 会在每次停止后自动审查
- 如果工作未完成，Supervisor 会提供反馈，Agent 继续执行
- 重复直到 Supervisor 确认工作完成
### 工作原理
1. Agent 完成任务并停止，触发 Claude Code 的 Stop Hook
2. Supervisor（一个 Claude 实例）执行严格的审查工作
3. 如果工作未完成或质量不佳，Supervisor 提供反馈
4. Agent 根据反馈继续工作
5. 重复直到 Supervisor 确认工作完成
### Statusline显示
可以在Claude code里输入以下指令，帮你配置好Statusline显示。
```text
/statusline 帮我配置statusline脚本，里面调用 `ccc supervisor-mode` 命令，这个命令会输出 on 或者 off，我希望显示成类似 ... | supervisor on 这样的效果。
```
## Patch 命令：用 ccc 替代 `claude` 命令
通过替换系统中的 `claude` 命令，让任何调用 `claude` 的工具都使用配置了提供商的 `ccc` 命令。
```bash
# 用 ccc 替换 claude 命令（需要 sudo 权限）
sudo ccc patch
# 替换后，`claude` 命令现在会调用 ccc
claude --help # 显示 ccc 的帮助信息
# 恢复原始 claude 命令
sudo ccc patch --reset
```
## 配置说明
配置文件位置，默认为：`~/.claude/ccc.json`
### 完整配置示例
```json
{
"settings": {
"permissions": {
"defaultMode": "bypassPermissions"
},
"alwaysThinkingEnabled": true
},
"supervisor": {
"max_iterations": 20,
"timeout_seconds": 600
},
"claude_args": ["--verbose"],
"current_provider": "glm",
"providers": {
"glm": {
"env": {
"ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
"ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY_HERE",
"ANTHROPIC_MODEL": "glm-4.7"
}
},
"kimi": {
"env": {
"ANTHROPIC_BASE_URL": "https://api.moonshot.cn/anthropic",
"ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY_HERE",
"ANTHROPIC_MODEL": "kimi-k2-thinking",
"ANTHROPIC_SMALL_FAST_MODEL": "kimi-k2-0905-preview"
}
}
}
}
```
### 配置字段说明
| 字段 | 说明 |
| ------------------ | ------------------------------------- |
| `settings` | 所有提供商共享的 Claude Code 配置模板 |
| `supervisor` | Supervisor 模式配置（可选） |
| `claude_args` | 固定传递给 Claude Code 的参数（可选） |
| `current_provider` | 当前使用的提供商（由 ccc 自动管理） |
| `providers.{name}` | 提供商特定的 Claude Code 配置 |
### 提供商配置
每个提供商只需指定要覆盖的字段。常用字段：
| 字段 | 说明 |
| -------------------------------- | ------------------ |
| `env.ANTHROPIC_BASE_URL` | API 端点 URL |
| `env.ANTHROPIC_AUTH_TOKEN` | API 密钥/令牌 |
| `env.ANTHROPIC_MODEL` | 使用的主模型 |
| `env.ANTHROPIC_SMALL_FAST_MODEL` | 快速任务使用的模型 |
**合并方式**：提供商设置与基础模板深度合并。提供商的 `env` 优先于 `settings.env`。
### Supervisor 配置
| 字段 | 说明 | 默认值 |
| ----------------- | -------------------------------- | ------- |
| `max_iterations` | 当前会话强制停止前的最大迭代次数 | `20` |
| `timeout_seconds` | 每次 supervisor 调用的超时时间 | `600` |
### 自定义 Supervisor 提示词
创建 `~/.claude/SUPERVISOR.md` 来自定义 Supervisor 提示词。此文件会使用你自己的指令覆盖默认的审查行为。
### 环境变量
| 变量 | 说明 |
| ---------------- | ------------------------------------------ |
| `CCC_CONFIG_DIR` | 覆盖配置目录（默认：`~/.claude/`） |
```bash
# 使用自定义配置目录调试
CCC_CONFIG_DIR=./tmp ccc glm
```
## 从源码构建
```bash
# 构建所有平台
./build.sh --all
# 构建指定平台
./build.sh -p darwin-arm64,linux-amd64
# 自定义输出目录
./build.sh -o ./bin
```
**支持的平台：** `darwin-amd64`、`darwin-arm64`、`linux-amd64`、`linux-arm64`
## 开源许可证
MIT License - 详见 LICENSE 文件。