agent-peers

Agent-to-agent messaging for Claude Code and Codex. Independent sessions working in different tools and projects can ask each other questions, coordinate changes, and return answers to the conversation that asked. Each keeps its own context and workflow.

Ask Codex:

Find the Claude session working on the API. Ask which response shape it chose, then use its answer for the client.

Get started · Hermes plugin · opencode plugin · Compatibility · Reference

Why agent-peers

• Coordinate independent sessions. Claude ↔ Codex, Claude ↔ Claude, and Codex ↔ Codex, across repositories.

• Replies arrive in context. Agents receive messages while idle or busy, through their host's normal conversation handling.

• Local transport. Direct Unix sockets on the same machine and OS user. No extra service to run or account to configure.

Backed by live Claude/Codex round trips, Hermes routing tests, and Linux/macOS CI.

Related MCP server: claude-peers

Get started

Requires Node.js 22+, Linux or macOS, and compatible agent versions.

npm install -g agent-peers@next

Codex (MCP server)

codex mcp add agent-peers -- codex-peer

Start a new Codex session; its inbox opens within seconds, without a tool call, and it is listed as codex:<folder>-<id>. It can use send_peer(to, message) to contact a listed peer and receive replies automatically. Keep the server name agent-peers: under another name, the inbox opens only on the session's first list_peers or send_peer.

A Codex session is reachable on the app-server agent-peers uses: Codex's shared daemon by default, or a private app-server for headless workers. codex exec, -c overrides and --no-daemon run an embedded server that peers cannot reach. A worker answers peers on its own; to let a lead change its task mid-turn, put one sentence in its brief.

Claude Code

Uses Claude's native SendMessage; no MCP server is needed. Add this to your agent instructions:

Run agent-peers list to discover peers. Use SendMessage with a listed uds: address as to. Replies arrive in this conversation. Keep coordination useful and brief. Send what's new; link existing detail rather than repeating it. Reply when it adds value.

Inspect available peers or check your installation:

agent-peers list
agent-peers doctor

For local development diagnostics, start the integration with AGENT_PEERS_DEBUG=1 and inspect retained activity with agent-peers logs --json. Logs contain bounded metadata, timings, correlation IDs and failure categories; message bodies and raw errors are excluded. See logging configuration and limits. Existing processes need a normal restart to inherit the setting.

Hermes (experimental)

A native plugin lets Hermes contact Claude and Codex, with private replies to the originating conversation. Sending requires the documented Hermes fork; stock Hermes supports discovery only.

hermes plugins install ThomasMarcelis/agent-peers --enable

Complete the dependency setup and injection grant. A Hermes conversation stays unlisted and opens a private reply inbox on its first send; it becomes reachable by others only through a stable name it claims (experimental), scoped to its profile. Discord routing is verified; CLI/Desktop lifecycle behavior remains experimental.

opencode (experimental)

opencode 2.x can load a plugin that exposes the same four tools, list_peers, send_peer, claim_name and release_name, with the same names and input schemas as Codex:

opencode plugin add agent-peers@next

Restart opencode after installation. The plugin registers the tools immediately and starts one bridge child per opencode server; every project location in that server shares it. A session becomes reachable after its first prompt or after its first tool call, even if it never calls agent-peers itself. After an opencode or bridge restart, its record is gone and it is unreachable until its next prompt or tool call; peers see a dead opencode: name as not-running until then.

opencode identity is tool-only: list_peers.self, claim_name, release_name and send_peer know the calling session. agent-peers whoami and agent-peers claim do not act for it, and OPENCODE_SESSION_ID is not an agent-peers identity. Peers need no opencode password or service URL; delivery uses the plugin's in-process host client and session.synthetic.

Support is experimental. This release was verified live only on a private opencode serve (a smoke run and a three-host run with Claude Code and Codex); the background service, --standalone and the TUI were not run, and no steering rate is claimed. Deterministic tests cover the plugin, bridge, registry, names and delivery. opencode unloads a project location after 60 minutes without session activity, which unbinds its sessions until their next prompt or tool call. Do not run one opencode session in two servers: the first live bridge owns it, the second refuses, and a resume: true delivery can start a second process-local runner in the other server. --auto auto-approves tool calls that are not explicitly denied, so do not use it with untrusted peers or sensitive repositories. See compatibility and reference.

Scope

Messages are peer input, never user approval. Host approval rules still apply. Delivery confirms inbox acceptance, not a model response. There is no offline mailbox; closed conversations become unreachable. See delivery and troubleshooting and the security boundary.

Stability · Contributing and tests · Changelog · MIT license