cccc-pair 0.2.6

Two‑AI orchestrator (tmux) for evidence‑first, small‑step collaboration

CCCC Pair — Dual‑AI Orchestrator (Telegram‑first, Evidence‑first)

Two best‑in‑class AI CLIs (Claude Code + Codex CLI) co‑drive your work as equal peers. They collaborate, self‑review, and ship small, reversible changes with built‑in governance. You monitor and approve from two places: tmux or your team’s Telegram chat.

Not a chatbot UI. Not an IDE plugin. A production‑minded orchestrator for 24/7, long‑running work.

Why It’s Different

• Dual‑AI Autonomy: peers continuously plan → build → critique → refine. They don’t wait for prompts; they follow a mailbox contract and change the world only with EVIDENCE (diff/tests/logs/benchmarks).
• Telegram‑first Collaboration: a 24/7 agent lives in your team chat. High‑signal summaries, one‑tap RFD decisions, explicit routing (a:/b:/both:) so normal conversation remains normal. Files flow both ways with captions and sidecars.
• Builder–Critic Synergy: peers challenge CLAIMs with COUNTERs and converge via verifiable EVIDENCE. In practice this beats single‑model quality on complex, multi‑day tasks.
• tmux Transparency: dual panes (PeerA/PeerB) + compact status panel. You can peek, nudge, or inject text without disrupting flows—and without a GUI.
• Governance at the Core (RFD): protected areas and irreversible changes raise Request‑For‑Decision cards in chat; approvals are written to a ledger and unlock execution.
• Team‑level Efficiency: one always‑on bot concentrates orchestration and approvals for the whole team. You reduce duplicated “per‑seat” sessions and still retain control.

What You Get

• Evidence‑first loop: tiny diffs/tests/logs; only green changes commit.
• Single‑branch queue: preflight git apply → (optional) lint/tests → commit.
• RFD closed loop: generate cards, gate protected paths/large diffs, unlock on decision.
• Telegram integration: explicit routing; /status, /queue, /locks, /rfd list|show, /showpeers on|off, file send/receive with meta.
• Ledger: append‑only .cccc/state/ledger.jsonl (patch/test/log/decision) for audit.

Requirements

• Python >= 3.9
• tmux (e.g., brew install tmux or sudo apt install tmux)
• git (preflight/commits)

Supported CLIs (current)

• Peer A: Claude Code CLI (recommended: MAX Plan)
• Peer B: Codex CLI (recommended: PRO Plan)

Install

• Recommended (pipx)
  • pipx install cccc-pair
• Or venv
  • python3 -m venv v && . v/bin/activate && pip install cccc-pair

Quick Start (5 minutes)

1. Initialize in your project repo

cccc init

This copies the scaffold to ./.cccc/ and appends /.cccc/** to .gitignore (Ephemeral).

2. Check environment

cccc doctor

3. (Optional) Enable Telegram

cccc token set   # paste your bot token; stored in .cccc/settings/telegram.yaml (gitignored)

4. Run orchestrator (tmux UI)

cccc run

tmux opens: left/right = PeerA/PeerB, bottom‑right = status panel. If token is present and autostart=true, the Telegram bridge starts automatically.

5. First‑time CLI setup (required)

• Install the two CLIs and make sure the binaries are on PATH:
  • claude ... (Claude Code)
  • codex ... (Codex CLI)
• Paste system prompts for best collaboration quality:
  • Open PEERA.md and copy its full content into a new file CLAUDE.md at your repo root (not tracked; .gitignore already ignores it). Claude Code CLI should load this as its system prompt.
  • Open PEERB.md and copy its full content into a new file AGENTS.md at your repo root (not tracked). Codex CLI should load this as its system prompt.
• Move any previous “project state” prompt into PROJECT.md at the repo root (recommended). The orchestrator will weave this into the runtime SYSTEM so both peers align on scope and goals.
• Verify or adjust the CLI commands in .cccc/settings/cli_profiles.yaml:
  • commands.peerA: "claude ..."
  • commands.peerB: "codex ..."
  • You can also override at runtime with env vars: CLAUDE_I_CMD, CODEX_I_CMD.

First Landing Checklist (Minimal)

Do just these to get a clean, working setup:

1. cccc init (creates ./.cccc and ignores runtime dirs)
2. cccc doctor (git/tmux/python)
3. Prepare system prompts (required once per repo)
   • Copy PEERA.md → CLAUDE.md (root)
   • Copy PEERB.md → AGENTS.md (root)
   • Put your brief/scope in PROJECT.md (root)
4. Optional Telegram (highly recommended)
   • cccc token set
   • cccc run (bridge autostarts) or cccc bridge start
5. Start work: cccc run (tmux panes + status panel)

That’s it. You can refine policies later.

Telegram Quickstart (Team Hub)

• Group routing: use explicit routes so normal chat stays normal
  • a: <text> / b: <text> / both: <text>
  • or /a ... /b ... /both ... (works with privacy mode)
• Get oriented
  • /status project stats; /queue handoff queue; /locks internal locks
  • /whoami shows your chat_id; /subscribe (if autoregister: open)
  • /showpeers on|off toggles Peer↔Peer summaries
• File exchange
  • Outbound (AIs → Telegram): save under .cccc/work/upload/outbound/<peer>/{photos,files}/
  • Optional caption: same‑name .caption.txt; force send‑as via .sendas (photo|document)
  • Sent files are deleted on success; outbound.reset_on_start: clear avoids blasting residuals on restart
  • Inbound (Telegram → AIs): bot writes <FROM_USER> with sidecar meta; peers act on it
• Governance: RFD cards in chat with Approve/Reject; decisions go to the ledger and unlock execution.

A Typical Session (End‑to‑End, ~3 minutes)

Goal: ship a small, reversible change with dual‑AI collaboration.

1. Explore (short)

• In Telegram (or tmux), route a brief idea to both: both: Add a section to README about team chat tips
• PeerA summarizes intent; PeerB asks 1 focused question if needed.

2. Decide (concise CLAIM)

• PeerA writes a CLAIM in peerA/to_peer.md with acceptance and constraints (≤150 lines; links to where to edit).
• PeerB COUNTERs if there’s a sharper place or a safer rollout.

3. Build (evidence‑first)

• PeerB produces a tiny unified diff in peerB/patch.diff (e.g., add a new README subsection) and a 1–2 line EVIDENCE note (tests OK/lines/paths/MID).
• Orchestrator preflights → applies → (optional) lint/tests → commits on green and logs to ledger.

4. Team visibility

• Telegram posts a concise summary (debounced); peers stay quiet unless blocked.
• If you need files (screenshots/spec PDFs), drop them to the bot with a caption; peers act on the inbound block with meta.

RFD is not required here. It triggers automatically only for protected areas or when you explicitly ask for a decision.

Recommended Stack (Pragmatic & Stable)

• AI CLIs: Claude Code (MAX Plan) + Codex CLI (PRO Plan) for robust, sustained workloads.
• Orchestrator: this project, with tmux for long‑lived panes and a compact panel.
• Transport & Governance: Telegram for team‑wide visibility, quick RFD decisions, and file exchange.

Folder Layout (after cccc init)

.cccc/
  adapters/telegram_bridge.py    # Telegram long‑poll bridge (MVP)
  settings/
    cli_profiles.yaml            # tmux/paste/type behavior; echo; idle regexes; self‑check
    policies.yaml                # patch queue size; allowlist; RFD gates
    roles.yaml                   # leader; specialties; rotation
    telegram.yaml                # token/autostart/allowlist/dry_run/routing/files
  mailbox/                       # peerA/peerB with to_user.md/to_peer.md/patch.diff; inbox/processed
  work/                          # shared workspace; upload inbound/outbound; ephemeral
  state/                         # ledger.jsonl, bridge logs, status/session; ephemeral
  logs/                          # extra logs; ephemeral
  orchestrator_tmux.py delivery.py mailbox.py panel_status.py prompt_weaver.py
  evidence_runner.py mock_agent.py

CLI Reference

• cccc init [--force] [--to PATH] — copy scaffold; preserves layout; excludes runtime dirs
• cccc doctor — check git/tmux/python/telegram
• cccc run — start orchestrator (tmux panes + status panel; autostarts bridge when configured)
• cccc token set|unset|show — manage Telegram token (gitignored)
• cccc bridge start|stop|status|restart|logs [-n N] [--follow] — control and inspect bridge
• cccc clean — purge .cccc/{mailbox,work,logs,state}/
• cccc version — show package version and scaffold path info

CLI prerequisites (summary)

• Peer A = Claude Code; Peer B = Codex CLI. Install and log in as required by each vendor.
• Ensure the binaries (claude, codex) are on PATH or set commands.peer*/CLAUDE_I_CMD/CODEX_I_CMD.

Key Configuration (snippets)

.cccc/settings/policies.yaml

patch_queue:
  max_diff_lines: 150
  allowed_paths: ["src/**","tests/**","docs/**","infra/**","README.md","PROJECT.md"]
rfd:
  gates:
    protected_paths: [".cccc/**","src/api/public/**"]
    large_diff_requires_rfd: false
handoff_filter:
  enabled: true
  cooldown_seconds: 15

.cccc/settings/telegram.yaml

token_env: "TELEGRAM_BOT_TOKEN"
autostart: true
discover_allowlist: true
autoregister: open
dry_run: false
files:
  enabled: true
  outbound_dir: ".cccc/work/upload/outbound"
outbound:
  reset_on_start: clear

FAQ / Troubleshooting

tmux panes not appearing?

• Install tmux (tmux -V), run in a TTY, then cccc run. Check cccc doctor.

Telegram bot silent?

• cccc token show (token saved?) → cccc bridge status (running?) → cccc bridge logs -n 200
• In group chats, route explicitly (a://a), and run /whoami or /subscribe once to register
• Ensure autostart: true, dry_run: false

Claude/Codex CLI not found?

• Install the CLIs and make sure the binaries are on PATH; otherwise set explicit commands:
  • Edit .cccc/settings/cli_profiles.yaml (commands.peerA|peerB) or
  • Export env vars before cccc run: CLAUDE_I_CMD="/path/to/claude ...", CODEX_I_CMD="/path/to/codex ..."

Where to put my project brief/policies?

• Put your project scope/brief in PROJECT.md (repo root). The orchestrator injects it into the runtime SYSTEM so both peers align.
• RFD/protected paths live in .cccc/settings/policies.yaml.

“This environment is externally managed” during install/build?

• Use a venv or pipx for publishing; avoid system Python for pip install of tools like build/twine.

RFD card not shown?

• Confirm ledger has kind:rfd; check bridge logs; verify gates and to_peer YAML format.

Security & Privacy

• Telegram token saved to .cccc/settings/telegram.yaml (gitignored) or env; do not commit secrets.
• Bridge redacts common secret patterns; keep mailbox content free of tokens.
• Orchestrator domain .cccc/** is runtime; do not commit state/logs/work/mailbox.

Roadmap (Selected)

• Role‑based approvals; multi‑sign gates; richer RFD templates with default options/expiry
• Artifact previews in chat; repro snippets; CI/CD hooks for release/rollback cards
• Optional safety scanners (ClamAV/DLP) for inbound files; Slack/Mattermost bridges

License

Apache (see LICENSE).