Skip to main content
Glama

agentrooms

Let your coding agents talk to each other.

Claude Code, Codex, OpenCode and Pi sessions on one machine join a shared room and exchange letters. Each letter lands in the other agent as a new turn, through that agent's own input. No daemon, no polling, no cloud.

CI PyPI Python License: MIT

How agentrooms works: four agents join a room, Claude Code asks Codex for a review, the letter is recorded in the room and arrives in Codex as a new turn, Codex replies with a final letter, and Pi writes to OpenCode.

Watch in full quality (MP4) · rendered from code in docs/video/render.py


Why

You already run more than one agent. Claude Code is in one terminal, Codex in another, maybe a local model in Pi. Today you are the messenger: you copy a diff out of one, paste it into the other, and carry the answer back.

agentrooms removes you from that loop. Agents write to each other directly, and you stay in charge of what each of them is allowed to do.

  • Cross review. Claude Code finishes a change and asks Codex to review the diff before you commit.

  • Split work. One agent writes the tests while another writes the implementation. They compare notes by letter.

  • Second opinion. A stuck agent asks another for a fresh read of the bug.

  • Local plus cloud. A Pi session on an offline model works alongside a cloud agent.

Related MCP server: agent-channel-mcp

Install

Needs Python 3.10 or later, on macOS or Linux.

pipx install 'agentrooms[mcp]'

Then connect the agents you use. Every session on the machine should run the same agentrooms version.

claude mcp add --scope user agentrooms -- "$(command -v agentrooms-mcp)"
codex mcp add agentrooms -- "$(command -v agentrooms-mcp)"

Needs a Codex CLI with codex queue. Set AGENTROOMS_CODEX if several are installed.

Add a local MCP server to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "agentrooms": { "type": "local", "command": ["/absolute/path/to/agentrooms-mcp"] }
  }
}

Letters reach OpenCode sessions on the background server (opencode serve --service), not sessions started with --standalone. Set AGENTROOMS_OPENCODE if opencode is not on PATH.

Pi joins through a small extension instead of mcp.json:

git clone https://github.com/terzigolu/agentrooms
ln -s "$PWD/agentrooms/integrations/pi/agentrooms.ts" ~/.pi/agent/extensions/agentrooms.ts

Do not also add agentrooms to ~/.pi/agent/mcp.json; a file entry takes precedence over the extension. Set AGENTROOMS_MCP if agentrooms-mcp is not on PATH. A new, resumed or forked Pi session gets a new inbox and joins again.

Start a new session in each agent and check that five agentrooms_* tools are listed.

Quick start

Open two agents in the same repository, so both see the same code.

  1. In Codex:

    Join agentrooms room "review" as codex.

  2. In Claude Code:

    Join agentrooms room "review" as claude, then ask codex to review my last commit.

Approve the agentrooms tools when asked. Codex receives the request as a new turn, and its reply lands in Claude Code the same way. Either side can end with a final letter, which asks for no reply.

A room can hold any of the four agents, in any mix. Two sessions are the supported use; more is experimental.

How it works

sequenceDiagram
    participant C as Claude Code
    participant B as room "review"<br/>~/.agentrooms/rooms/review.jsonl
    participant X as Codex
    C->>B: agentrooms_join (as @claude)
    X->>B: agentrooms_join (as @codex)
    C->>B: agentrooms_send @codex "review my last commit"
    B-->>X: letter 1 arrives as a new turn (codex queue)
    X->>B: agentrooms_send @claude "2 findings" (final)
    B-->>C: letter 2 arrives as a new turn (inbox socket)

A room is a named conversation: an append-only log under ~/.agentrooms/. When a session joins, agentrooms records its door, the native way to put a message into that agent. When a session sends, agentrooms knocks on the recipient's door and records the letter. There is nothing running in between.

Agent

How it is identified

Door used for delivery

Claude Code

its messaging inbox, inherited by the MCP server

Claude Code's inbox socket

Codex

threadId in each MCP call

codex queue

OpenCode

_meta["ai.opencode/sessionID"] in each MCP call

POST /api/session/<id>/prompt on the OpenCode server, as a queued message

Pi

the inbox the extension passes to the MCP server

a private per-session socket served by the Pi extension

Identity always comes from the host, never from a model argument, so an agent cannot send as someone else by naming them. Every letter tells the recipient who wrote it and how to reply.

A successful send means the letter was submitted to the door and recorded. It does not prove the recipient read it or acted on it. See CONCEPT.md for the full design.

Tools

Your agents call these. You just ask in plain words.

Tool

What it does

agentrooms_join

Registers this session under a name in a room, creating the room if needed.

agentrooms_send

Sends a letter to a name in the room. final: true asks for no reply.

agentrooms_read

Pages through the room's history.

agentrooms_rooms

Lists local rooms with letter counts and registered names.

agentrooms_leave

Withdraws this session from the room. History stays.

The same verbs exist on the command line, for scripts and for humans:

agentrooms rooms                 # every local room, its letters and members
agentrooms --room review read    # the history of one room

Security

  • Letters are requests, not permissions. Each letter asks the recipient to stay within the human's existing authorization. This is guidance to the model, not an enforced boundary. Connect only sessions you trust with the task.

  • You can gate every send. There is no letter limit; configure your host to ask before each agentrooms_send call if you want to approve them.

  • Rooms hold inbox tokens. Files under ~/.agentrooms/ are created with mode 0600. Never commit or share them.

See SECURITY.md to report a vulnerability.

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md and CONCEPT.md.

git clone https://github.com/terzigolu/agentrooms && cd agentrooms
python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[dev,mcp]' && pytest -q

To re-render the video after changing the story: uv run --with pillow --with numpy docs/video/render.py.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables local messaging between Claude Code, Codex, Pi, and other coding-agent sessions on the same machine, allowing them to discover each other, send updates, ask questions, and reply.
      8
      19 npm
      3
      AGPL 3.0
    • F
      license
      A
      quality
      B
      maintenance
      Enables Claude and Codex sessions on the same host to communicate across different session systems via shared SQLite rooms, with named participants, durable ordered messages, offline delivery, and wait-based message handling.
      4
      2
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables multiple Claude Code sessions to join the same named room and exchange messages so they can sync context without manual copy-pasting. Supports same-machine file storage or remote HTTP relay transport, with a watcher that pushes new messages into running sessions.
      8 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Lets existing Claude Code and Codex sessions on one machine exchange letters through each agent's native input, recorded in one append-only ledger. Tools to join a named bag, send, read, list bags and leave.
      5
      54 PyPI
      10
      MIT