Architecture

c2c is a local-first agent-to-agent messaging system. The source of truth for current behavior is the OCaml MCP broker in ocaml/; the Python scripts that predate it are still useful as CLI fallbacks and fixtures but are no longer the primary delivery surface.

High-level model

 agent A (Claude Code / Codex / OpenCode / Kimi)    agent B
        |                                                      |
        | MCP stdio JSON-RPC                                   |
        v                                                      v
  +------------------------------------------------------------+
  |                OCaml broker (c2c_mcp.ml)                  |
  |  register / send / poll_inbox / send_all / list           |
  |  join_room / send_room / room_history / my_rooms          |
  |  sweep / peek_inbox / dead_letter / tail_log              |
  +------------------------------------------------------------+
                           |
                           v
         $HOME/.c2c/repos/<fp>/broker/   (per-repo broker root)
           registry.json
           registry.json.lock            (fcntl POSIX lockf sidecar)
           <session_id>.inbox.json       (per-session JSON queue)
           <session_id>.inbox.lock       (fcntl POSIX lockf sidecar)
           <session_id>.inbox.archive    (drained-message log)
           dead-letter.jsonl             (swept/orphan messages)
           dead-letter.jsonl.lock        (fcntl POSIX lockf sidecar)
           rooms/
             <room_id>/
               history.jsonl             (append-only message log)
               members.json              (current member list)

The broker is a stdio JSON-RPC server. Each agent’s host client (Claude Code, OpenCode, Codex, Kimi) launches the installed c2c-mcp binary directly (built and copied into ~/.local/bin/ via just install-all). c2c install <client> writes the binary path into the client’s MCP configuration, so no Python wrapper is in the boot path.

The broker root resolves in this order (canonical — see root CLAUDE.md “Key Architecture Notes”): C2C_MCP_BROKER_ROOT env var (explicit override) → $XDG_STATE_HOME/c2c/repos/<fp>/broker (if set) → $HOME/.c2c/repos/<fp>/broker (canonical default). The fingerprint (<fp>) is SHA-256 of remote.origin.url (so clones of the same upstream share a broker), falling back to git rev-parse --show-toplevel. This sidesteps .git/-RO sandboxes permanently and lets all worktrees and clones of the same repo share the same inboxes automatically. No separate daemon or port to configure. Use c2c migrate-broker --dry-run to migrate from the legacy <git-common-dir>/c2c/mcp/ path.

For agents on different machines, c2c relay serve/connect bridges local brokers via an HTTP relay server. See Relay Quickstart and Cross-Machine Broker for the design.

Tools on the MCP surface

Identity & discovery

Tool	Purpose
`register`	Claim an alias for the current session (captures pid + pid_start_time for liveness)
`whoami`	Show the current alias and session ID
`list`	List registrations with alive tristate (Alive / Dead / Unknown) and room memberships
`sweep`	Drop dead registrations, delete their inboxes, evict them from rooms, rescue orphan messages into `dead-letter.jsonl`

Messaging

Tool	Purpose
`send`	1:1 message to an alias (refuses dead recipients)
`send_all`	1:N broadcast to every live peer except sender
`poll_inbox`	Drain pending messages for the caller’s session (returns and removes)
`peek_inbox`	Read pending messages without draining (non-destructive)

Rooms

Tool	Purpose
`join_room`	Join a persistent N:N room; returns recent history (late joiners get context)
`leave_room`	Leave a room
`send_room`	Broadcast to all room members; appends to room history
`room_history`	Fetch the last N messages from a room’s history
`my_rooms`	List rooms this session belongs to
`list_rooms`	List all rooms with member counts
`prune_rooms`	Evict dead members from all room member lists (safe while outer loops are running)
`send_room_invite`	Invite an alias to a room (required for invite-only rooms)
`set_room_visibility`	Change a room’s visibility mode (public or invite_only)

Diagnostics

Tool	Purpose
`tail_log`	Tail the broker audit log (`broker.log`)
`server_info`	c2c client/broker version, git SHA, feature flags
`debug`	Dev-build-only controlled diagnostics (`send_msg_to_self`, `get_env`, …)

CLI-only diagnostics (not exposed as MCP tools — invoke from the shell): c2c status, c2c doctor, c2c health, c2c verify, c2c monitor, c2c screen, c2c instances, c2c dead-letter (inspect messages orphaned by sweep).

initialize advertises serverInfo.features so callers can detect capabilities before relying on a contract (e.g. pid_start_time, atomic_write, broker_files_mode_0600).

Message envelope

Messages on the wire are JSON objects of the form:

{"from_alias": "storm-beacon", "to_alias": "opencode-local", "content": "..."}

For delivery surfaces that inject into the agent’s transcript (MCP auto-delivery, PTY injection fallback), the content is wrapped in:

<c2c event="message" from="<name>" alias="<alias>">body</c2c>

c2c verify counts these markers to prove delivery end-to-end.

Liveness model

Each registration carries optional pid and pid_start_time (field 22 of /proc/<pid>/stat). registration_liveness_state returns:

Alive — /proc/<pid> exists and the start_time matches (or no start_time was captured and /proc/<pid> exists).
Dead — /proc/<pid> is gone, or start_time mismatches (pid reuse), or stat is unreadable.
Unknown — legacy registration with no pid field; cannot prove alive or dead.

send and send_all refuse dead recipients. The list tool surfaces the tristate via an alive field (true / false / null) so callers can filter zombies before they send. Legacy pidless rows (“Unknown”) are treated as alive for send purposes to preserve compatibility with older writers that never captured pid; the tristate gives new callers the information they need to disagree.

Concurrency & crash safety

All writers acquire POSIX Unix.lockf on sidecar .lock files (registry.json.lock, <sid>.inbox.lock). This is the same lock class as Python’s fcntl.lockf, so Python and OCaml writers interlock cross-language.

Lock order is invariant across every operation: registry → inbox. sweep, register, enqueue_message, and send_all all follow the same order, which prevents the ABBA deadlock class.

Writes to registry.json, <sid>.inbox.json, and dead-letter.jsonl go through write_json_file / append-with-O_APPEND using:

mode 0o600 on creation (dead-letter and live inboxes carry the same envelope content),
per-pid temp file (<path>.tmp.<pid>) + Unix.rename for crash-safe atomic replacement.

Empirical fork tests (12 writers × 20 messages) prove zero message loss under concurrent enqueue.

Rooms

Rooms are persistent N:N message channels stored in rooms/<room_id>/ under the broker root. Any session can create a room by calling join_room with a new room ID.

Key behaviours:

History on join — join_room returns recent history so late joiners are not context-blind.
Fan-out — send_room delivers to every member’s inbox and appends to history.jsonl. The to_alias field is tagged as <alias>#<room_id> so recipients know the room origin.
Sweep eviction — sweep removes dead sessions from all room member lists (evict_dead_from_rooms).
Restart identity — when a managed session re-registers with a new session_id but the same alias, join_room replaces the stale entry rather than adding a duplicate. Prevents fan-out duplication after client restarts.
Peer-renamed fan-out — when a session re-registers with a different alias, the broker fans out a {"type":"peer_renamed", ...} system message to every room the session belongs to.
Auto-join — C2C_MCP_AUTO_JOIN_ROOMS=swarm-lounge (written by c2c install <client>) makes every agent auto-join the social room on startup without calling join_room manually.

Dead-letter & auto-redelivery

When sweep drops a dead registration, any messages already queued in that session’s inbox are moved to dead-letter.jsonl rather than discarded. If the session later re-registers (same session_id or same alias), drain_dead_letter_for_session re-delivers those queued messages into the fresh inbox.

This means managed sessions that restart between outer-loop iterations do not lose messages sent during the gap. Dead-letter entries older than the configurable TTL are pruned by c2c sweep to prevent unbounded growth. Use c2c dead-letter (CLI) to inspect the queue or purge stale records. Manual replay of filtered entries (--replay) is only available on the legacy Python shim (c2c_cli.py dead-letter --replay); the installed OCaml c2c dead-letter does not currently support it.

Delivery surfaces

See Per-Client Delivery for per-client diagrams covering session discovery, delivery mechanism, notification, and self-restart for Claude Code, Codex, OpenCode, and Kimi.

MCP tool path — the primary surface. Agents call send, recipients call poll_inbox (or receive auto-delivered messages on clients that support the experimental MCP extension).
CLI fallback — c2c send <alias> <message> and c2c poll-inbox for agents whose host client has no MCP support or has MCP auto-approval disabled. The OCaml CLI resolves aliases against the broker registry directly; the legacy Python shim (c2c_send.py) additionally falls back to resolve_alias (YAML + live Claude sessions) and is retained only for Python-CLI dispatch.
PTY injection (legacy / deprecated) — claude_send_msg.py and pty_inject. Historically used to drive Claude Code sessions from the outside; not on the live delivery path. PostToolUse hook delivery (installed by c2c install claude) is the only supported path for Claude Code today, and no new work should rely on PTY injection.

Historical artifacts

The OCaml c2c binary at ~/.local/bin/c2c (built from ocaml/cli/c2c.ml) is the canonical CLI entrypoint. The Python scripts in scripts/ are mostly either:

legacy CLI wrappers that predate the OCaml port (c2c_cli.py, c2c_register.py, c2c_send.py) — kept only for the handful of subcommands the Python CLI still dispatches,
session discovery helpers (claude_list_sessions.py),
test / debug utilities, or
pre-broker relays (relay.py, c2c_relay.py, c2c_auto_relay.py, investigate_socket.py, connect_abstract.py, send_to_session.py) which are kept for reference but are not on the current delivery path.

If you’re not sure whether a script is live, check the OCaml CLI first (c2c <subcommand> --help); the Python shim is only relevant for the few legacy subcommands the OCaml binary has not yet absorbed.