ccc - Claude Code Supervisor

English | 中文文档

Why ccc?

ccc is a CLI tool that enhances Claude Code with two core features:

1. Supervisor Mode: ⭐ Automatic task review that ensures high-quality, deliverable work
2. Seamless Provider Switching: Switch between Kimi, GLM, MiniMax, and other providers with one command

Better than ralph-claude-code:

• Supervisor Mode uses a Stop Hook triggered review with a strict framework that significantly improves task completion and quality.
• Unlike ralph's signal-based exit detection, ccc's Supervisor forks the full session context to evaluate actual work quality.
• This prevents fake completions where AI claims "done" but the result has poor quality or unresolved issues.

Quick Start

1. Install

Option A: One-line install (Linux / macOS)

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

Option B: Download from Releases

Download the binary for your platform (ccc-darwin-arm64, ccc-linux-amd64, etc.) and install to /usr/local/bin/.

2. Configure

If you already have ~/.claude/settings.json, the first time you run ccc it will prompt to migrate and automatically generate the ccc config at ~/.claude/ccc.json.

You can also create the config file manually:

{
  "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"
      }
    }
  }
}

Security Warning: bypassPermissions allows Claude Code to execute tools without confirmation. Only use this in trusted environments.

3. Use

# Show help
ccc --help

# Switch to a provider and run Claude Code
ccc glm

# Run with current provider
ccc

# Pass any Claude Code arguments
ccc glm -p

4. Validate (Optional)

Verify your provider configuration:

# Validate current provider
ccc validate

# Validate all providers
ccc validate --all

Supervisor Mode (Recommended)

Supervisor Mode is the most valuable feature of ccc. It automatically reviews the Agent's work after each stop and provides feedback if incomplete.

How to Use

1. Start ccc, chat with the Agent to confirm requirements and approach:

   ccc
   

2. Enable Supervisor Mode using the slash command:

   /supervisor OK, start executing
   

3. The Agent will execute the task, and Supervisor will automatically review after each stop

   • If work is incomplete, Supervisor provides feedback and Agent continues
   • This repeats until Supervisor confirms the work is complete

How It Works

1. Agent completes a task and stops, triggering Claude Code's Stop Hook
2. Supervisor (a Claude instance) performs a strict review
3. If work is incomplete or low quality, Supervisor provides feedback
4. Agent continues with the feedback
5. This repeats until Supervisor confirms the work is complete

Statusline Display

You can configure the statusline in Claude Code to show Supervisor Mode status:

/statusline Help me configure a statusline script that calls `ccc supervisor-mode` command, which outputs "on" or "off". I want it to display like "... | supervisor on"

Patch Command: Replace claude with ccc

Make ccc your default Claude Code by replacing the system claude command.

# Replace claude command with ccc (requires sudo)
sudo ccc patch

# After patching, `claude` command now uses ccc
claude --help    # Shows ccc help

# Restore original claude command
sudo ccc patch --reset

Configuration

Config file location, default: ~/.claude/ccc.json

Configuration Merge Strategy

User settings are preserved. ccc follows these principles when merging configuration:

1. Priority: User's settings.json configuration has the highest priority
2. Provider settings: Provider-specific configuration from ccc.json overrides base settings
3. Base settings: The settings field in ccc.json serves as a shared template

What Gets Preserved

• ✅ User-installed plugins (enabledPlugins) - never overwritten
• ✅ Manual settings.json edits (permissions, sandbox, etc.) - fully preserved
• ✅ User-configured hooks (PreToolUse, SessionStart, etc.) - respected
• ✅ Environment variables you manually set in settings.json - ccc never edits them

What Gets Managed

• 🤖 Supervisor Stop hook - automatically added/ensured
• ⚙️ Hook execution flags - disableAllHooks and allowManagedHooksOnly set to false to ensure hooks work

Environment Variable Conflicts (Hard Guard)

Claude Code's settings.json env field overrides environment variables passed by ccc when launching claude (empirically verified). If settings.json contains keys that would shadow the provider env, switching providers silently fails (wrong base_url / token / model).

ccc refuses to start claude — and refuses to run ccc validate — when it detects such conflicts. Instead of silently editing your file, ccc prints the offending keys (without their values, to avoid leaking secrets) and tells you how to fix it. ccc never modifies the env field of your settings.json.

A key is considered conflicting if it:

• starts with ANTHROPIC_ or CLAUDE_, or
• collides with any key defined in ccc.json's base / provider env.

How to fix: remove those keys from ~/.claude/settings.json's env and move provider-related configuration into providers.<name>.env in ~/.claude/ccc.json.

How It Works

When you run ccc:

1. Your existing settings.json is read (if it exists)
2. Configuration is merged with priority: user > provider > base
3. Environment variables from provider are passed via command line (not written to settings.json)
4. Supervisor Stop hook is added (if needed) while preserving your other hooks

This ensures your manual configuration is never lost!

{
  "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"
      }
    }
  }
}

Config Fields

Provider Configuration

Each provider only needs to specify the fields it wants to override. Common fields:

How merging works: Provider settings are deep-merged with the base template. Provider env takes precedence over settings.env.

Supervisor Configuration

Custom Supervisor Prompt

Create ~/.claude/SUPERVISOR.md to customize the Supervisor prompt. This file overrides the default review behavior with your own instructions.

Environment Variables

# Debug with custom config directory
CCC_CONFIG_DIR=./tmp ccc glm

Building from Source

# Build for all platforms
./build.sh --all

# Build for specific platforms
./build.sh -p darwin-arm64,linux-amd64

# Custom output directory
./build.sh -o ./bin

Supported platforms: darwin-amd64, darwin-arm64, linux-amd64, linux-arm64

License

MIT License - see LICENSE file for details.