CCCC

Local-first Multi-agent Collaboration Kernel

A lightweight multi-agent framework with infrastructure-grade reliability.

Chat-native, prompt-driven, and bi-directional by design.

Run multiple coding agents as a durable, coordinated system — not a pile of disconnected terminal sessions.

Three commands to go. Zero infrastructure, production-grade power.

English | 中文 | 日本語

Why CCCC

• Durable coordination: working state lives in an append-only ledger, not in terminal scrollback.
• Visible delivery semantics: messages have routing, read, ack, and reply-required tracking instead of best-effort prompting.
• One control plane: Web UI, CLI, MCP, and IM bridges all operate on the same daemon-owned state.
• Multi-runtime by default: Claude Code, Codex CLI, ChatGPT Web, Gemini CLI, and the rest of the first-class runtimes can collaborate in one group.
• Local-first operations: one pip install, runtime state in CCCC_HOME, and remote supervision only when you choose to expose it.

The Problem

Using multiple coding agents today usually means:

• Lost context — coordination lives in terminal scrollback and disappears on restart
• No delivery guarantees — did the agent actually read your message?
• Fragmented ops — start/stop/recover/escalate across separate tools
• No remote access — checking on a long-running group from your phone is not an option

These aren't minor inconveniences. They're the reason most multi-agent setups stay fragile demos instead of reliable workflows.

What CCCC Does

CCCC is a single pip install with zero external dependencies — no database, no message broker, no Docker required. Yet it gives you the pieces fragile multi-agent setups usually lack:

| Capability | How | |---|---| | Single source of truth | Append-only ledger (ledger.jsonl) records every message and event — replayable, auditable, never lost | | Reliable messaging | Read cursors, attention ACK, and reply-required obligations — you know exactly who saw what | | Unified control plane | Web UI, CLI, MCP tools, and IM bridges all talk to one daemon — no state fragmentation | | Multi-runtime orchestration | Claude Code, Codex CLI, OpenCode, ChatGPT Web, Gemini CLI, and 6 more first-class runtimes, plus custom for everything else | | Role-based coordination | Foreman + peer model with permission boundaries and recipient routing (@all, @peers, @foreman) | | Local-first runtime state | Runtime data stays in CCCC_HOME, not your repo, while Web Access and IM bridges cover remote operations |

How CCCC looks

Quick Start

Install

# Stable channel (PyPI)
pip install -U cccc-pair

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

Requirements: Python 3.9+, macOS / Linux / Windows

Upgrade

cccc update

Use cccc update --check to inspect the detected install type and the command that would run.

Launch

cccc

Open http://127.0.0.1:8848 — by default, CCCC brings up the daemon and the local Web UI together.

Create a multi-agent group

cd /path/to/your/repo
cccc attach .                              # bind this directory as a scope
cccc setup --runtime claude                # configure MCP for your runtime
cccc actor add foreman --runtime claude    # first actor becomes foreman
cccc actor add implementer --runtime codex # add a peer
cccc group start                           # start all actors
cccc send "Please inspect the repo and propose the first safe task." --to foreman
cccc tracked-send "Please take the first concrete task and reply with validation evidence." \
  --to implementer \
  --title "First concrete task" \
  --outcome "The change and validation evidence are reported"

You now have two agents collaborating in a persistent group with full message history, delivery tracking, and a web dashboard. The daemon owns delivery and coordination, and runtime state stays in CCCC_HOME rather than inside your repo.

Programmatic Access (SDK)

Use the official SDK when you need to integrate CCCC into external applications or services:

pip install -U cccc-sdk
npm install cccc-sdk

The SDK does not include a daemon. It connects to a running cccc core instance.

Architecture

graph TB
    subgraph Agents["Agent Runtimes"]
        direction LR
        A1["Claude Code"]
        A2["Codex CLI"]
        A3["ChatGPT Web<br/>GPT-5.x via MCP"]
        A4["Gemini CLI"]
        A5["+ 6 more + custom"]
    end

    subgraph Daemon["CCCC Daemon · single writer"]
        direction LR
        Ledger[("Ledger<br/>append-only JSONL")]
        ActorMgr["Actor<br/>Manager"]
        Auto["Automation<br/>Rules · Nudge · Cron"]
        Ledger ~~~ ActorMgr ~~~ Auto
    end

    subgraph Ports["Control Plane"]
        direction LR
        Web["Web UI<br/>:8848"]
        CLI["CLI"]
        MCP["MCP<br/>(stdio)"]
    end

    subgraph IM["IM Bridges"]
        direction LR
        TG["Telegram"]
        SL["Slack"]
        DC["Discord"]
        FS["Feishu"]
        DT["DingTalk"]
        WC["WeCom"]
        WX["Weixin"]
    end

    A1 <-->|MCP tools<br/>PTY/headless| Daemon
    A2 <-->|MCP tools<br/>PTY/headless| Daemon
    A3 <-->|Browser delivery<br/>Remote MCP| Daemon
    A4 <-->|MCP tools| Daemon
    A5 <-->|MCP tools| Daemon
    Daemon <--> Ports
    Web <--> IM

Key design decisions:

• Daemon is the single writer — all state changes go through one process, eliminating race conditions
• Ledger is append-only — events are never mutated, making history reliable and debuggable
• Ports are thin — Web, CLI, MCP, and IM bridges are stateless frontends; the daemon owns all truth
• Runtime home is CCCC_HOME (default ~/.cccc/) — runtime state stays out of your repo

Supported Runtimes

CCCC orchestrates agents across 10 first-class runtimes, with custom available for everything else. Each actor in a group can use a different runtime.

| Runtime | Integration | Command / Surface | |---------|-------------|-------------------| | Claude Code | Auto MCP setup | claude | | Codex CLI | Auto MCP setup | codex | | ChatGPT Web | Remote MCP + Browser Delivery | chatgpt.com conversation | | Gemini CLI | Auto MCP setup | gemini | | Droid | Auto MCP setup | droid | | Amp | Auto MCP setup | amp | | Auggie | Auto MCP setup | auggie | | Kimi CLI | Auto MCP setup | kimi | | Neovate | Auto MCP setup | neovate | | OpenCode | Auto MCP setup via runtime config | opencode | | Custom | Manual | Any command |

cccc setup --runtime claude    # auto-configures MCP for this runtime
cccc runtime list --all        # show all available runtimes
cccc doctor                    # verify environment and runtime availability

Actors can run as PTY (embedded terminal) or headless (structured I/O without a terminal). Claude Code and Codex CLI support both modes; headless gives the daemon tighter delivery and streaming control.

ChatGPT Web / GPT-5.x local development

ChatGPT Web can join a CCCC group as a real actor, not just an external chat window. CCCC delivers group messages into one explicitly bound ChatGPT conversation through browser delivery, while ChatGPT calls back into CCCC through a single actor-bound remote MCP connector.

In supported ChatGPT sessions, GPT-5.x can participate in local development with the same coordination layer as Claude Code or Codex: receive routed messages, reply visibly through CCCC, inspect and edit repository files, run scoped shell/git commands, and coordinate with peer agents. When the selected GPT-5.x chat exposes the CCCC MCP connector, this gives eligible ChatGPT environments an experience close to a native Codex-style local coding agent. It can also turn ChatGPT web capacity into additional local-development agent capacity, reducing pressure on native Codex usage for work that can run well through ChatGPT Web.

GPT-5.x Pro note: GPT-5.x Pro currently cannot be treated as a CCCC local-development runtime. ChatGPT Pro sessions do not expose the third-party CCCC MCP connector, and their web fetcher may block private or public tunnel URLs before they reach CCCC. That means Pro has no reliable local access in CCCC: no MCP tools, no repository reads, no shell/git work, and no No-MCP resource fallback. Use a GPT-5.x ChatGPT session that can see the CCCC connector for local development; use Pro only for external advisory work when you manually provide the needed context.

Zero-to-ready setup:

1. Start cccc web, expose it through a public HTTPS URL, then enter that URL in Settings > Global > Web Access.
   • Recommended options: Cloudflare Tunnel, ngrok, Tailscale Funnel, or a reverse proxy such as Caddy/Nginx on a public HTTPS host.
   • ChatGPT cannot use localhost, plain HTTP, or private tailnet-only URLs as the MCP server URL.
2. Create an Admin Access Token in Settings > Global > Web Access.
3. Open `Settings > Global > ChatG