Skip to main content
Glama
README.md
<div align="center">

# 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](https://github.com/terzigolu/agentrooms/actions/workflows/ci.yml/badge.svg)](https://github.com/terzigolu/agentrooms/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/agentrooms)](https://pypi.org/project/agentrooms/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/agentrooms/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/terzigolu/agentrooms/blob/main/LICENSE)

![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.](https://raw.githubusercontent.com/terzigolu/agentrooms/main/docs/assets/how-it-works.gif)

<sub>[Watch in full quality (MP4)](https://github.com/terzigolu/agentrooms/raw/main/docs/assets/how-it-works.mp4) · rendered from code in [`docs/video/render.py`](docs/video/render.py)</sub>

</div>

---

## 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.

## Install

Needs Python 3.10 or later, on macOS or Linux.

```sh
pipx install 'agentrooms[mcp]'
```

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

<details open>
<summary><b>Claude Code</b></summary>

```sh
claude mcp add --scope user agentrooms -- "$(command -v agentrooms-mcp)"
```
</details>

<details open>
<summary><b>Codex</b></summary>

```sh
codex mcp add agentrooms -- "$(command -v agentrooms-mcp)"
```

Needs a Codex CLI with `codex queue`. Set `AGENTROOMS_CODEX` if several are installed.
</details>

<details open>
<summary><b>OpenCode</b></summary>

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

```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`.
</details>

<details open>
<summary><b>Pi</b></summary>

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

```sh
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.
</details>

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

```mermaid
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](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:

```sh
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](.github/SECURITY.md) to report a vulnerability.

## Contributing

Issues and pull requests are welcome. Start with
[CONTRIBUTING.md](.github/CONTRIBUTING.md) and [CONCEPT.md](CONCEPT.md).

```sh
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](LICENSE)