FAQ

Frequently asked questions about CCCC.

Positioning

How does CCCC compare to native agent teams and other tools?

vs. native agent teams (Claude Code subagents/agent teams and similar single-vendor features). Native teams give you the smoothest experience inside one vendor and one session — if you only run Claude Code and your work fits in a session, they are a great default. CCCC adds what a single vendor structurally cannot:

• Cross-vendor groups — Claude Code, Codex CLI, Grok Build, Kimi CLI, ChatGPT Web, and more in one group, so you can route work to whichever model or subscription fits each role.
• Durable state — groups, messages, delivery/read/reply facts, and tasks live in an append-only ledger owned by a daemon. Restarting a terminal (or your machine) does not dissolve the team.
• Remote operations — check, pause, resume, and redirect a running group from Telegram, Slack, Discord, Feishu, DingTalk, WeCom, or Weixin.
• An audit trail — every message and its delivery state is replayable for review and debugging.

vs. parallel task runners (worktree/task-board tools). These tools excel at fanning out isolated tasks in parallel. CCCC's focus is the coordination layer they intentionally skip: agents that talk to each other, choose whether a message should interrupt or wait in Mail, hand off tracked work, and expose delivery/read/reply state — plus daemon-owned lifecycle and IM-side operations. The two approaches compose well: keep a task runner for fan-out and use CCCC as the durable coordination plane.

vs. IM assistant gateways (personal-assistant products that live in your chat app). Those products put a general assistant in your messenger. CCCC is built for delivery-grade collaboration on real work: tracked tasks with owners and outcomes, explicit delivery/read/reply semantics, multi-agent groups bound to a repository scope, and a tiered token and capability-allowlist security model.

In short: CCCC does not replace your agents — it is the coordination layer that turns them into a durable, observable team. See also Positioning for what CCCC deliberately is and is not.

Installation & Setup

How do I install CCCC?

# Stable product distribution from PyPI (recommended)
python -m pip install -U cccc-pair

# From TestPyPI (explicit RC testing)
python -m pip install -U --pre \
  --index-url https://test.pypi.org/simple \
  --extra-index-url https://pypi.org/simple \
  cccc-pair

# From source
git clone https://github.com/ChesterRa/cccc
cd cccc
pip install -e .

Supported PyPI platform wheels include stable Python plus a private, version-matched experimental Rust implementation for opt-in performance evaluation. An experimental Rust-only standalone preview is also available for deployment testing:

# macOS / Linux
curl -fsSL https://chesterra.github.io/cccc/install.sh | sh

# Windows CMD or PowerShell
powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12; Invoke-RestMethod 'https://chesterra.github.io/cccc/install.ps1' | Invoke-Expression"

The preview has no Python fallback or implementation switching and is not the recommended replacement for the pip product.

Why does cccc still start an older installation after an upgrade?

CCCC does not delete commands owned by another Python environment or installer. Run cccc doctor and inspect the Installation section. It shows the current launcher, the first command selected by PATH, and every duplicate. The standalone installer puts its default directory first for new terminals; an existing terminal must be reopened (or its PATH refreshed). Custom install directories and CCCC_NO_MODIFY_PATH=1 require you to move that directory to the front manually. When PATH still selects the old command, run the newly installed executable by the absolute path printed by the installer to get the current diagnostic report.

How do I uninstall CCCC without losing my groups?

Run cccc home first and stop the running product. Pip installations should be removed with python -m pip uninstall cccc-pair. For a standalone preview, verify the complete .cccc-standalone ownership marker and remove only the owned executable and marker; do not delete a shared command directory. CCCC intentionally retains CCCC_HOME, so groups, ledgers, settings, credentials, and browser profiles remain available after reinstall. Exact macOS/Linux and Windows standalone steps are in the dual-engine distribution guide.

How do I upgrade from an older version (0.3.x)?

You must uninstall the old version first:

# For pipx users
pipx uninstall cccc-pair

# For pip users
pip uninstall cccc-pair

# Remove any leftover binaries
rm -f ~/.local/bin/cccc ~/.local/bin/ccccd

Then install the new version. Note that 0.4.x has a completely different command structure from 0.3.x.

What are the system requirements?

• Python 3.11+ on macOS, Linux, or Windows for the recommended PyPI distribution
• At least one supported agent runtime CLI

The experimental standalone Rust preview does not require Python or a Rust toolchain, but supports fewer platforms and contains only the Rust implementation.

How do I choose the Python or Rust implementation?

cccc status
cccc rust              # persist experimental Rust and launch CCCC
cccc python            # persist stable Python and launch CCCC
cccc rust doctor       # persist experimental Rust, then run one command

These selectors belong to the recommended pip distribution. Python is the stable default; cccc rust explicitly opts into the experimental Rust implementation, whose complete feature and integration parity is not promised. Rust is retained as a bounded evaluation surface for measured native benefits; use cccc python for reliability-critical workflows or to switch back. Supported PyPI platform wheels contain Rust privately; other platforms receive the universal Python wheel and report Rust as unavailable. The selector validates the payload and stops the active Web/daemon pair. It never installs a second command or silently falls back. The standalone preview contains Rust only and therefore does not expose implementation switching.

How do I check if CCCC is working?

cccc status
cccc doctor

These show implementation availability, Python version, agent runtimes, and daemon status.

Does a leftover cccc-web.lock mean CCCC is still running?

No. The operating-system file lock is authoritative; the file may retain the last owner's PID after a crash. cccc automatically reclaims an unlocked file, replaces the PID, and starts its embedded daemon when the Web process starts. Manual lock deletion or a separate cccc daemon start is not required. If CCCC reports that another instance is running, that process still holds the real file lock and should be stopped normally.

Why does an embedded browser open a physical Chrome window on Linux?

Projected browsers require Xvfb to stay off the host desktop. Install xvfb (and optionally x11vnc for the VNC viewer), run cccc doctor, then use Restart ChatGPT browser. Current CCCC fails browser startup when Xvfb is missing instead of silently falling back to the host DISPLAY.

Agents

Which AI agents are supported?

• Claude Code (claude)
• Cline CLI (cline)
• Codex CLI (codex)
• GitHub Copilot CLI (copilot)
• Cursor CLI (cursor-agent)
• Devin CLI (devin)
• Kiro CLI (kiro-cli)
• Kilo Code CLI (kilo)
• Antigravity CLI (agy)
• Droid (droid)
• Grok Build (grok)
• Hermes Agent (hermes)
• Kimi CLI (kimi)
• OpenCode (opencode)
• Amp (amp)
• Auggie (auggie)
• Custom (manual fallback; provide your own command and MCP wiring)

What's the difference between Foreman and Peer?

• Foreman: The first enabled actor. Coordinates work, receives system notifications, can manage other actors.
• Peer: Independent expert. Has their own judgment, can only manage themselves.

How do I add a custom agent?

cccc actor add my-agent --runtime custom --command "my-custom-cli"

Agent won't start?

1. Check the terminal tab for error messages
2. Verify MCP is configured: cccc setup --runtime <name>
3. Ensure the CLI is installed and in PATH
4. Try: cccc actor restart <actor_id>

Messaging

How do I send a message to a specific agent?

cccc send "Please do X" --to agent-name

Or in the Web UI, type @agent-name in your message.

Agent isn't responding to my messages?

1. Check if the agent is running (green indicator in Web UI)
2. Check the inbox: cccc inbox --actor-id <agent-id>
3. Look at the terminal tab for errors
4. Try restarting the agent

How do read receipts work?

Agents call cccc_inbox_read to receive and consume the next ordered batch. The returned batch boundary is committed cumulatively; bootstrap previews and Web polling do not consume messages.

Remote Access

How do I access CCCC from my phone?

Option 1: Cloudflare Tunnel

cloudflared tunnel --url http://127.0.0.1:8848

Option 2: IM Bridge

cccc im set telegram --token-env TELEGRAM_BOT_TOKEN
cccc im start

Option 3: Tailscale

CCCC_WEB_HOST=$(tailscale ip -4) cccc

Is it safe to expose the Web UI?

Before exposing the Web UI, create an Admin Access Token in Settings > Web Access and then sign in with that token.

Use Cloudflare Access or Tailscale for additional security.

Performance

How much resources does CCCC use?

• Daemon: Minimal (Python async)
• Web UI: Standard React app
• Agents: Depends on the runtime

The ledger file is getting large

CCCC supports snapshot/compaction. Large blobs are stored separately in the blobs/ directory.

How do I reduce message latency?

1. Ensure agents are already running
2. Use specific @mentions instead of broadcasts
3. Keep the daemon running (don't restart frequently)

Troubleshooting

Daemon won't start

cccc daemon status  # Check if already running
cccc daemon stop    # Stop existing instance
cccc daemon start   # Start fresh

Port 8848 is unavailable

CCCC_WEB_PORT=9000 cccc

On Windows, Hyper-V / WSL / WinNAT / HNS can reserve a TCP port even when no process is listening on it. If 8848 still fails to start and you do not see an owning PID, check the excluded port ranges:

netsh interface ipv4 show excludedportrange protocol=tcp

If 8848 falls inside one of those ranges, start CCCC on a different port:

cccc web --port 9000

MCP not working

cccc setup --runtime <name>  # Re-run setup
cccc doctor                  # Check configuration

Web UI not loading

1. Check daemon is running: cccc daemon status
2. Check the port: http://127.0.0.1:8848/
3. Check browser console for errors
4. Try a different browser

Concepts

What is a Working Group?

A working group is like an IM group chat with execution capabilities. It includes:

• An append-only ledger (message history)
• One or more actors (agents)
• Optional scopes (project directories)

What is the Ledger?

The ledger is an append-only event stream that stores all messages, state changes, and decisions. It's the single source of truth for a working group.

What is MCP?

MCP (Model Context Protocol) is how agents interact with CCCC. It exposes a rich tool surface for messaging, context management, automation, and system control.

What is a Scope?

A scope is a project directory attached to a working group. Agents work within scopes, and events are attributed to scopes.