Claude-code-minoan claude-peers

Discover, message, and coordinate AI coding agents (Claude Code, Codex CLI) running on the same machine via a shared Unix socket broker backed by SQLite. Supports cross-session task delegation, peer summaries, and session lifecycle management. Triggers on 'peer agents', 'cross-session communication', 'message Codex', 'inter-agent messaging', 'coordinate agents'.

install

source · Clone the upstream repo

git clone https://github.com/tdimino/claude-code-minoan

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/tdimino/claude-code-minoan "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/integration-automation/claude-peers" ~/.claude/skills/tdimino-claude-code-minoan-claude-peers && rm -rf "$T"

manifest: skills/integration-automation/claude-peers/SKILL.md

source content

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, routing messages between Claude Code and Codex CLI sessions.

Client Types

Client	Push notifications	Message delivery	Config
claude-code	Yes ( `claude/channel` )	Instant — messages pushed into session	`settings.json` MCP entry
codex	No	Poll — must call `check_messages` each turn	`~/.codex/config.toml` MCP entry
cli	No	Manual via `bun ~/tools/claude-peers-mcp/cli.ts send <id> <msg>`	N/A

Workflow Patterns

Task delegation: Send a focused task description to a Codex or Claude peer via

send_message

. Include file paths, acceptance criteria, and which branch to work on. The receiving agent picks it up on its next turn.

Code review handoff: After completing work, message a peer with the diff summary and ask for review. The peer can respond with findings via

send_message

Parallel exploration: Multiple agents working the same repo can use

set_summary

to advertise what they're investigating, preventing duplicate work. Use

list_peers

with scope

repo

to see who else is in the same codebase.

Session lifecycle: Use

kill_peer

to terminate a stuck, unresponsive, or completed peer's agent session. This kills the parent process (e.g., the Codex CLI), not just the MCP subprocess, and cleans up the peer record.

CLI Reference

bun ~/tools/claude-peers-mcp/cli.ts status        # Broker health + all peers with [type] tags
bun ~/tools/claude-peers-mcp/cli.ts peers          # Quick peer listing
bun ~/tools/claude-peers-mcp/cli.ts send <id> <msg> # Send from terminal (tagged as unverified)
bun ~/tools/claude-peers-mcp/cli.ts kill <id>       # Kill a peer's agent session (SIGTERM to parent)
bun ~/tools/claude-peers-mcp/cli.ts kill-broker     # Stop the broker daemon

Gotchas

Codex sandbox: Codex's macOS seatbelt sandbox blocks socket
```
connect()
```
in
```
workspace-write
```
mode. Codex sessions currently require
```
--dangerously-bypass-approvals-and-sandbox
```
or
```
danger-full-access
```
sandbox to reach the broker. This is a Codex sandbox limitation, not a peers issue — tracked at Codex issue #11095.
Codex has no push: Codex agents must call
```
check_messages
```
proactively — messages are invisible until polled.
Permission allow-list:
```
mcp__claude-peers__send_message
```
may not be in the auto-allow list. The user may need to approve it on first use or add it to
```
settings.json
```
permissions.
Broker must be running: The broker is managed by launchd (
```
com.minoan.claude-peers-broker
```
). If peers can't connect, check:
```
launchctl list | grep claude-peers
```
.
Stale socket: If the broker crashes, the socket file persists. On restart, the broker detects and removes it automatically.
TCP fallback: Set
```
CLAUDE_PEERS_TCP=1
```
in the broker's env to also listen on TCP port 7899. Clients use TCP when
```
CLAUDE_PEERS_URL
```
is set (e.g.,
```
CLAUDE_PEERS_URL=http://127.0.0.1:7899
```
).