cccc-pair
Advanced tools
Global multi-agent delivery kernel with working groups, scopes, and an append-only collaboration ledger
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.
pip install, runtime state in CCCC_HOME, and remote supervision only when you choose to expose it.Using multiple coding agents today usually means:
These aren't minor inconveniences. They're the reason most multi-agent setups stay fragile demos instead of reliable workflows.
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, Grok Build, 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 |
# 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
cccc update
Use cccc update --check to inspect the detected install type and the command that would run.
cccc
Open http://127.0.0.1:8848 — by default, CCCC brings up the daemon and the local Web UI together.
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.
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.
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:
CCCC_HOME (default ~/.cccc/) — runtime state stays out of your repoCCCC orchestrates agents across 12 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 |
| Grok Build | Auto MCP setup | grok |
| Hermes Agent | Auto MCP setup | hermes |
| 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 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:
cccc web, expose it through a public HTTPS URL, then enter that URL in Settings > Global > Web Access.
localhost, plain HTTP, or private tailnet-only URLs as the MCP server URL.Settings > Global > Web Access.Settings > Global > ChatGPT Web Model, create/start the single ChatGPT Web Model actor, then create and copy its MCP URL.Settings > Apps > Advanced settings > Create app, then create a custom MCP app with these fields:
CCCCCCCC local workspace connectorNo AuthNo Auth.Full setup and troubleshooting: ChatGPT Web Model Runtime.
CCCC implements IM-grade messaging semantics, not just "paste text into a terminal":
@all, @peers, @foreman, or specific actor IDsreply_to with quoted contextUse ordinary send for chat, questions, and quick requests. Use tracked-send when delegated work needs a durable owner, outcome, evidence, handoff, or acceptance trail. @all remains available for announcements or urgent shared coordination, but it should not be the default way to start concrete work.
Messages are delivered to actor runtimes through the daemon-managed delivery pipeline, and the daemon tracks delivery state for every message.
A built-in rules engine handles operational concerns so you don't have to babysit:
| Policy | What it does |
|---|---|
| Nudge | Reminds agents about unread messages after a configurable timeout |
| Reply-required follow-up | Escalates when required replies are overdue |
| Actor idle detection | Notifies foreman when an agent goes silent |
| Keepalive | Periodic check-in reminders for the foreman |
| Silence detection | Alerts when an entire group goes quiet |
Beyond built-in policies, you can create custom automation rules:
The built-in Web UI at http://127.0.0.1:8848 provides:
@mention autocomplete and reply threading| Chat | Terminal |
|---|---|
 |  |
For accessing the Web UI from outside localhost:
CCCC_WEB_HOST=0.0.0.0 cccccloudflared tunnel --url http://127.0.0.1:8848CCCC_WEB_HOST=$TAILSCALE_IP cccc127.0.0.1 means local-only, while 0.0.0.0 means localhost plus your LAN IP on a normal local host. If CCCC is running inside WSL2's default NAT networking, 0.0.0.0 only exposes Web inside WSL; for LAN devices, use WSL mirrored networking or a Windows portproxy/firewall rule.Save stores the target binding. If Web was started by cccc or cccc web, use Apply now in Settings > Web Access to perform the short supervised restart. If Web is managed by Docker, systemd, or another external supervisor, restart that service instead.Start / Stop are only for Tailscale remote access and do not rebind the already-running Web socket.Bridge your working group to your team's IM platform:
cccc im set telegram --token-env TELEGRAM_BOT_TOKEN
cccc im start
| Platform | Status |
|---|---|
| Telegram | ✅ Supported |
| Slack | ✅ Supported |
| Discord | ✅ Supported |
| Feishu / Lark | ✅ Supported |
| DingTalk | ✅ Supported |
| WeCom / 企业微信 | ✅ Supported |
| Weixin / 微信 | ✅ Supported |
DingTalk and WeCom support streaming replies (AI Card and aibot streaming respectively); other platforms deliver final messages.
From any supported platform, use plain text or /send @foreman <message> for normal coordination, reserve /send @all <message> for true broadcasts, use /status to check group health, and use /pause / /resume to control operations — all from your phone.
# Lifecycle
cccc # start daemon + web UI
cccc daemon start|status|stop # daemon management
# Groups
cccc attach . # bind current directory
cccc groups # list all groups
cccc use <group_id> # switch active group
cccc group start|stop # start/stop all actors
# Actors
cccc actor add <id> --runtime <runtime>
cccc actor start|stop|restart <id>
# Messaging
cccc send "message" --to foreman
cccc tracked-send "delegated work" --to implementer --title "Task title" --outcome "Done criterion"
cccc send "announcement" --to @all # explicit broadcast
cccc reply <event_id> "response"
cccc tail -n 50 -f # follow the ledger
# Inbox
cccc inbox # show unread messages
cccc inbox --mark-read # mark all as read
# Operations
cccc doctor # environment check
cccc setup --runtime <name> # configure MCP
cccc runtime list --all # available runtimes
# IM
cccc im set <platform> --token-env <ENV_VAR>
cccc im start|stop|status
Agents interact with CCCC through a compact action-oriented MCP surface. Core tools are always present, and optional capability packs add more surfaces only when enabled.
| Surface | Examples |
|---|---|
| Session & guidance | cccc_bootstrap, cccc_help, cccc_project_info |
| Messaging & files | cccc_inbox_list, cccc_inbox_mark_read, cccc_message_send, cccc_message_reply, cccc_file |
| Group & actor control | cccc_group, cccc_actor |
| Coordination & state | cccc_context_get, cccc_coordination, cccc_task, cccc_agent_state, cccc_context_sync |
| Automation & memory | cccc_automation, cccc_memory, cccc_memory_admin |
| Capability-managed extras | cccc_capability_*, cccc_space, cccc_terminal, cccc_debug, cccc_im_bind |
Agents with MCP access can self-organize: read inbox state, reply visibly, coordinate around tasks, refresh agent state, and enable extra capabilities when the current job actually needs them.
| Scenario | Fit |
|---|---|
| Multiple coding agents collaborating on one codebase | ✅ Core use case |
| Human + agent coordination with full audit trail | ✅ Core use case |
| Long-running groups managed remotely via phone/IM | ✅ Strong fit |
| Multi-runtime teams (e.g., Claude + Codex + Gemini) | ✅ Strong fit |
| Single-agent local coding helper | ⚠️ Works, but CCCC's value shines with multiple participants |
| Pure DAG workflow orchestration | ❌ Use a dedicated orchestrator; CCCC can complement it |
CCCC is a collaboration kernel — it owns the coordination layer and stays composable with external CI/CD, orchestrators, and deployment tools.
CCCC_HOME (~/.cccc/), not in your repository.CCCC_HOME/config/.For detailed security guidance, see SECURITY.md.
| Section | Description |
|---|---|
| Getting Started | Install, launch, create your first group |
| Use Cases | Practical multi-agent scenarios |
| Web UI Guide | Navigating the dashboard |
| IM Bridge Setup | Connect Telegram, Slack, Discord, Feishu, DingTalk, WeCom, Weixin |
| Group Space | NotebookLM knowledge integration |
| ChatGPT Web Model Runtime | Connect MCP-capable ChatGPT GPT-5.x as a CCCC actor |
| Capability Allowlist | MCP capability governance |
| Best Practices | Recommended patterns and workflows |
| FAQ | Frequently asked questions |
| Operations Runbook | Recovery, troubleshooting, maintenance |
| CLI Reference | Complete command reference |
| SDK (Python/TypeScript) | Integrate apps/services with official daemon clients |
| Architecture | Design decisions and system model |
| Features Deep Dive | Messaging, automation, runtimes in detail |
| CCCS Standard | Collaboration protocol specification |
| Daemon IPC Standard | IPC protocol specification |
pip install -U cccc-pair
pip install -U --pre \
--index-url https://test.pypi.org/simple/ \
--extra-index-url https://pypi.org/simple/ \
cccc-pair
git clone https://github.com/ChesterRa/cccc
cd cccc
pip install -e .
uv venv -p 3.11 .venv
uv pip install -e .
uv run cccc --help
start.ps1.cccc doctor reports Windows PTY: NOT READY, run python -m pip install pywinpty or reinstall with uv pip install -e ..scripts/build_web.ps1 for the bundled UI and scripts/build_package.ps1 for a full package build.cd docker
docker compose up -d # then create an Admin Access Token in Settings > Web Access before exposing beyond localhost
The Docker image bundles Claude Code, Codex CLI, Gemini CLI, and Factory CLI. See docker/ for full configuration.
The 0.4.x line is a ground-up rewrite. Clean uninstall first:
pipx uninstall cccc-pair || true
pip uninstall cccc-pair || true
rm -f ~/.local/bin/cccc ~/.local/bin/ccccd
Then install fresh and run cccc doctor to verify your environment.
The tmux-first 0.3.x line is archived at cccc-tmux.
📱 Join our Telegram group: t.me/ccccpair
Share workflows, troubleshoot issues, and connect with other CCCC users.
Contributions are welcome. Please:
cccc version, OS, exact commands, and reproduction stepsCCCC_HOME — never commit it to the repoFAQs
Global multi-agent delivery kernel with working groups, scopes, and an append-only collaboration ledger
We found that cccc-pair demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
pnpm 11.5 now recognizes npm staged publish approvals in release metadata, preventing those releases from being mistaken for lower-trust package publishes.
Security News
Federal audit finds NIST lacked a plan to clear the NVD backlog, wasted funds on duplicate work, and delayed use of CISA data.
Research
/Security News
A mini Shai-Hulud campaign compromised Red Hat Cloud Services npm packages to steal developer and CI/CD secrets during installation.