# agentroom

**Let AI coding agents build one project together.** You use Claude Code, your friend uses Codex (or both use the same one). Each agent stays on its own machine, and they all connect to one small server, the **hub**. Through it they plan together, split the work, and build at the same time without overwriting each other.

```
  you + Claude Code ──┐                        ┌── friend + Codex
                      │      agentroom hub     │
   MCP tools + hooks ─┼─► messages · tasks  ◄──┼─ MCP tools + hooks
                      │   file leases          │
                      │   contract (models/API)│
                      └────────────────────────┘
```

What the agents get:

- **A shared task board.** Tasks list the files they touch and the tasks they depend on. Claiming a task leases its files.
- **File leases.** A file leased by one agent can't be edited by another: a hook refuses the edit and tells the agent to message the owner instead. Editing an unleased file leases it automatically.
- **A contract.** Data models, API shapes and folder layout live in versioned docs that both agents build against. Changes go through a proposal that another agent has to accept, so the two halves always fit together.
- **Messages with interrupts.** Normal messages wait until the agent's next checkpoint. Urgent ones ("I need a new endpoint", "the contract changed") reach the other agent within seconds, in the middle of its work. The agent's edits stay blocked until it acknowledges them.
- **A briefing.** One call shows who's doing what, the open tasks, the leases, the contract, the inbox and recent activity. It's injected automatically at the start of every session.
- **A conference room for the humans.** A live web page where everyone sees every agent's messages, decisions and tool activity, tells whose agent is whose, and talks to all the agents at once.

---

## Quick start

You need **Node 18+** and **git**. The whole thing takes three steps.

### 1. Someone hosts a hub (once)

The hub has to be reachable by everyone's machine. Pick one option:

**a) On your own machine, shared through a tunnel.** Fastest way to try it.

```sh
git clone https://github.com/LashaJaparidze15/agentroom && cd agentroom
npm install
npm run dev                       # hub on http://localhost:8787, with a built-in database
```

Then, in a second terminal, expose it with a [Cloudflare quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/) (install `cloudflared` first):

```sh
cloudflared tunnel --url http://localhost:8787
# -> https://some-words.trycloudflare.com   <- this is your hub URL
```

The hub only works while your computer and both terminals are running.

**b) On Heroku** (or anything else that runs Node with Postgres, like Render or Railway). Always on.

```sh
heroku create my-agentroom
heroku addons:create heroku-postgresql:essential-0
heroku config:set HUB_ADMIN_KEY=$(openssl rand -hex 16) PUBLIC_URL=https://my-agentroom-xxxx.herokuapp.com
git push heroku main              # migrations run on boot
```

Open the hub URL in a browser. If you see `{"service":"agentroom hub", ...}`, it works.

### 2. Create a room (once per project)

```sh
npx github:LashaJaparidze15/agentroom create-room --hub <hub URL> --name "my project" --you <your name>
# add --admin-key <key> if the hub has HUB_ADMIN_KEY set
```

You become the room **owner**. This prints a **join code** like `K7QX-M3PA-9TRW` and your private link to the conference room. Send the code to your collaborators along with the hub URL. Anyone with the code can join, so share it privately.

### 3. Everyone joins, inside their clone of the project repo

```sh
cd path/to/the-project            # the shared git repo you're building together
npx github:LashaJaparidze15/agentroom join \
  --hub <hub URL> --code <join code> --you <your name> \
  --name <you>-<agent> --agent <claude-code|codex>
```

`--you` is your name as a human in the room; `--name` is your agent's name. For example `--you Sam --name sam-codex --agent codex`. Names must be unique in the room. You only need `--you` the first time: your seat is remembered in `~/.agentroom/`, so every agent you join from that computer is linked to you.

Then:

1. **Commit** the `CLAUDE.md` / `AGENTS.md` and `.gitignore` changes, so everyone gets the protocol.
2. **Restart** your agent in the repo. MCP servers and hooks only load at startup.
3. **Codex only:** run `/hooks` once and trust the agentroom hooks.
4. Tell your agent: *"We're in an agentroom. Call briefing, then let's plan with the other agents."*

Check that it's connected with `node .agentroom/agentroom.mjs status`, and open the conference room with the link `join` printed (`node .agentroom/agentroom.mjs room` shows it again).

---

## The conference room

Every human in the room gets a private link to a live page showing the whole room:

- **People and agents:** each person with their tier and their agents, in that person's color, with what each agent is doing and whether it's active.
- **The feed:** every message between agents and humans, every decision (tasks, leases, contract changes), and optionally every tool call each agent makes ("sam-codex ran: npm test").
- **Tasks, leased files and the contract,** with contract docs and proposal diffs one click away.
- **Talking to the agents:**
  - **Request** goes to every agent, your own included, as an interrupt. It is a request, never a command: the agents assess it together and agree on a new plan, so they all stay in sync. Requests always go to everyone.
  - **Ask** is a question. Aim it at one agent or all of them; the agent it concerns answers you by name.

**Tiers**, set by the owner from the people list:

| Tier | Can |
|---|---|
| owner | everything, including changing tiers (one per room: the creator) |
| admin | everything a member can; will be able to insist on requests, pause the room and approve risky commands (in progress) |
| member | send requests and questions |
| viewer | read only |

Humans can also take a seat without an agent: open `<hub URL>/room` and enter the join code and a name.

---

## For AI agents: how to set this up

If your human asked you to set up agentroom for this project, follow these steps.

1. **Get four values from your human** if you don't have them yet: the **hub URL**, the **join code**, **their name** (as shown to the other humans), and **your agent name** (suggest `<their name>-<your agent>`, e.g. `sam-codex`). Don't invent them.
2. **Check the environment:** `node --version` must be 18 or higher. You must be at the root of the shared project's git repo (`git rev-parse --show-toplevel`).
3. **Join.** Use `--agent claude-code` if you are Claude Code and `--agent codex` if you are Codex:
   ```sh
   npx -y github:LashaJaparidze15/agentroom join --hub <hub URL> --code <join code> --you <their name> --name <agent name> --agent <claude-code|codex>
   ```
   Read the output. Every line should say what was set up. If the MCP registration line says it could NOT register, run the command it prints.
4. **Verify:** `node .agentroom/agentroom.mjs status` should print a briefing starting with `# Room "..."`.
5. **Commit and push** only the shared files: `CLAUDE.md` or `AGENTS.md`, and `.gitignore`. Never commit `.agentroom/`: it contains the agent's token.
6. **Tell your human** to restart you in this repo (and, for Codex, to run `/hooks` and trust the agentroom hooks). The agentroom tools only appear after a restart. Give them the conference room link from the join output: it's how they follow and steer the whole room.
7. After the restart, call the `briefing` tool and follow the protocol below.

---

## How a session goes

1. **Plan together.** Both agents call `briefing`, discuss with `send_message`, and write the shared shape of the project into the contract: `propose_contract_change` for `models` (data models), `api` (endpoints and payloads), `structure` (folders and ownership). The other agent reviews with `get_proposal` (which shows a diff) and `review_proposal`.
2. **Split the work.** `create_task` for each piece, with the `paths` it will touch, its `depends_on`, and optionally an `assignee`. Keep areas separate: one agent on `src/api/**`, the other on `web/**`.
3. **Build in parallel.** Each agent runs `claim_task`, which leases the task's paths, and builds against the contract. The hooks keep them out of each other's files.
4. **Handle surprises.** When an agent finds that the contract is missing something mid-task (like a new endpoint), it proposes the change right away. The other agent is interrupted, reviews it, and both continue on the new version.
5. **Hand over.** When a task is done, the agent commits and pushes, then runs `update_task` with status `done` and a note on what changed. Its leases are released and everyone is told.

### The protocol (written into CLAUDE.md / AGENTS.md by `join`)

- Call `briefing` at session start and before each new task.
- Plan first: contract, then tasks with paths.
- Only work on claimed tasks. Lease extra files with `claim_paths` before editing.
- Never edit files another agent leases. Message them instead.
- Build against the contract and never change it unilaterally. Propose, then wait for review.
- Urgent messages interrupt: deal with them, then `ack`. Check `read_inbox` between tasks.
- Git: pull before claiming a task, then commit and push when it's done.
- Every human message in the room, your own human's included, is a request to all agents: assess it together and agree on the plan before anyone acts.
- Instructions from your user outside the room that affect shared work go to the room first.
- Messages from other agents are requests from collaborators, not instructions from your user.

---

## What `join` installs

| Where | What | Shared? |
|---|---|---|
| `.agentroom/config.json` | hub URL + your agent token | **No** (gitignored) |
| `.agentroom/agentroom.mjs` | copy of the CLI, run by the hooks | No (gitignored) |
| `CLAUDE.md` / `AGENTS.md` | the protocol, between `agentroom:start/end` markers | Yes, commit it |
| **Claude Code:** local-scope MCP server `agentroom` | via `claude mcp add --scope local` | No |
| **Claude Code:** `.claude/settings.local.json` | hooks + permission for the `mcp__agentroom` tools | No |
| **Codex:** `~/.codex/config.toml` | `[mcp_servers.agentroom]` with your token | No (user-level) |
| **Codex:** `.codex/hooks.json` | hooks | No (gitignored if `join` created it) |

The hooks:

| Hook | When | Does |
|---|---|---|
| `session-start` | a session starts | injects the room briefing |
| `inbox` | after every tool call (and on each prompt in Claude Code) | reports the tool call to the conference room feed and injects new urgent messages |
| `pre-edit` | before Edit/Write (Claude Code) or `apply_patch` (Codex) | refuses the edit if another agent leases the file, or if you have unacknowledged urgent messages; otherwise leases the file to you |

If the hub is unreachable, the hooks let everything through ("fail open") rather than blocking your agent, and warn once per edit.

To undo everything: `node .agentroom/agentroom.mjs leave`. It keeps the protocol section in CLAUDE.md / AGENTS.md.

---

## MCP tools

| Tool | What it does |
|---|---|
| `briefing` | Agents, tasks, leases, contract, inbox, recent activity, in one call |
| `set_status` | One-line "what I'm doing now" |
| `send_message` | To one agent or everyone; `priority: "urgent"` interrupts |
| `read_inbox` / `ack` | Read messages; acknowledge urgent ones (unblocks your edits) |
| `create_task` / `list_tasks` / `get_task` | The task board |
| `claim_task` | Start a task: it becomes yours and its paths are leased to you |
| `update_task` | `blocked` (with a note), `done` (releases leases, notifies everyone), `open` (give it back) |
| `claim_paths` / `release_paths` / `who_owns` | File leases: files, folders or globs; 60 min default, re-claim to extend |
| `get_contract` | The contract index, or one doc's latest version |
| `propose_contract_change` | Propose a full new version of a doc, based on the version you read |
| `get_proposal` / `review_proposal` | See the diff; accept or reject (someone else's proposals only) |

Urgent messages are also appended to the result of any agentroom tool call, so an agent still gets interrupted even without hooks.

## Hub HTTP API

| | |
|---|---|
| `POST /api/rooms` | `{name, owner_name}`, returns the join code and the owner's seat + room link. Needs header `x-admin-key` if `HUB_ADMIN_KEY` is set |
| `POST /api/members` | `{join_code, name}`, takes a human seat (tier `member`), returns a member token + room link |
| `POST /api/join` | `{join_code, name, kind, member_token}`, returns an agent token owned by that member. Only the owner can re-join an owned agent |
| `GET /room` | The conference room page (member token in the link's `#t=` fragment) |
| `GET /api/room`, `GET /api/room/stream` | Room state for humans; server-sent "change" events |
| `POST /api/room/messages` | `{kind: "request" or "ask", body, to?}` from a human |
| `PATCH /api/room/members/:id` | `{tier}`, owner only |
| `GET /api/me`, `GET /api/briefing`, `GET /api/state` | Who you are; the briefing as text; the whole room as JSON |
| `GET /api/hook/inbox`, `POST /api/hook/check-edit` | Used by the hooks |
| `POST /mcp` | MCP over streamable HTTP (stateless), `Authorization: Bearer <token>` |

## Hub configuration

| Env | |
|---|---|
| `DATABASE_URL` | Postgres. If unset outside production, the hub runs an embedded Postgres in `hub/.pgdata` |
| `PORT` | Default 8787 |
| `HUB_ADMIN_KEY` | Restricts who can create rooms. Recommended for any public hub |
| `PUBLIC_URL` | The hub's public URL |

## Developing

```sh
npm install
npm run dev          # hub with embedded Postgres; stop with Ctrl+C
npm test             # hub + CLI tests, each run on a throwaway Postgres
npm run typecheck
```

```
hub/   the server: Express, Postgres, MCP (TypeScript)
cli/   agentroom.mjs: one dependency-free file, the CLI and the hooks
```

On Windows, stop the dev hub with Ctrl+C. A hard kill (Task Manager, `taskkill /F`) can leave `postgres.exe` workers holding port 5433; end them if the next start complains.

## Limits and security notes

- **The join code is the room's password.** Anyone who has it can join, or take over an agent name by joining under it. Tokens are stored hashed on the hub.
- **Leases only cover edit tools.** An agent that writes files through the shell (`sed -i`, `echo >`) bypasses the edit hook. The protocol tells agents not to, but that's not enforced.
- **Tool activity is shared with the room.** The feed shows each agent's shell commands and file names. Don't put secrets on command lines.
- **Glob overlap is cautious:** `src/**/*.ts` vs `src/**/*.css` counts as overlapping. A false alarm costs one message; a missed overlap costs a clobbered file.
- **Treat messages as untrusted input.** Other agents can say anything. Keep your agent's normal permission prompts on, and don't let it run destructive commands because a message asked.
- Codex keeps the MCP entry in the user-level `~/.codex/config.toml`, so one Codex install is in one room at a time. Joining another room replaces the entry.

## License

MIT