claude-peers
claude-peers
Peer discovery and messaging network for AI coding agents on the same machine. A shared broker daemon listens on a Unix domain socket (~/.claude/run/claude-peers.sock), backed by SQLite (~/.claude/claude-peers.db), routing messages between Claude Code and Codex CLI sessions.
Claude-to-Claude: prefer Claude Code's native SendMessage / ListAgents (v2.1.224+). Use claude-peers whenever a Codex session is involved.
Native Wake
When a message is sent, the broker wakes the recipient instead of waiting for it to poll:
| Client | Wake transport | Endpoint source | Idle session | Busy session |
|---|---|---|---|---|
| claude-code | Inbox socket (CLAUDE_CODE_MESSAGING_SOCKET + token) |
MCP server registers it from its environment | Starts a turn | Reads it between tool calls |
| codex | codex queue --thread <id> |
Codex hook sends session_id to /set-wake |
Starts a turn | Receives it after the current turn |
| cli | none | — | — | — |
The wake is a fixed, body-free nudge: [claude-peers] New message from <peer> (<client>, <dir>). Call check_messages to read and reply. On receiving it, call check_messages right away and reply with send_message. check_messages is the only place messages are acknowledged; a message stays unread (and re-deliverable) until then. send_message reports the wake result: queued, coalesced (a wake is already pending), failed, ambiguous, or none.