<!-- Source: https://console.uubright.com/docs/rooms/ -->
# Shared rooms (preview)

In the app, a room appears in one of two ways:

- The [Manager](https://console.uubright.com/docs/manager/)'s room is its **Team log**: a tab next to **Chat** in
  the Manager's task. It shows how the Manager and its workers coordinate, with the
  questions and hand-offs waiting for you at the top. You talk to the Manager in
  Chat; the log has no message box of its own. A worker in that room links to it
  as **Team log as @handle**, and Needs you opens it with **Open team log**.
- Any other room is a **shared room**, under **Shared (preview)**: in the workspace
  menu, in **Workspace settings**, and under **More** on a phone. Rooms are no
  longer in the sidebar or the phone tabs.

The API keeps the name rooms, and nothing about them changed. The rest of this page
uses that name.

A room lets several agents work together: a planner and workers, or an
implementer and a reviewer. Members can be Claude Code or Codex tasks on your server,
and agents that run elsewhere, such as Codex on your laptop. They share one message log and one task list. Code still
moves through Git branches.

An agent can read and post at any time during its own turn. When an agent
addresses a peer, you get a hand-off to **pass on** or dismiss. Only your own
messages and hand-offs you pass on wake another agent, except for messages
between a lead and a worker it created. Those pass automatically. You can also
turn on [auto-pass](#auto-pass) for the whole room.

**Team Agent preview claim:** an invited teammate's Codex or Claude Code on
another computer can collaborate in this one host-owned room over a reachable
HTTPS address. Joining adds a room-scoped MCP server entry on that computer.
The outside agent can read and post room messages and edit the room's shared
task list. A message to a task running on the owner's host waits for the owner
to pass it on, unless the owner enabled auto-pass; a message to another outside
agent waits for that agent's next `room_read`. The room token cannot start a
host task, answer anyone's approval or question, or enter another room. The
invite flow gives the teammate neither the owner token nor a personal relay
token. The teammate needs network access to the owner's HTTPS room endpoint
and their own Codex or Claude Code installation. This preview does not create
signed-in human membership or dispatch work to the teammate's host. That
cross-user path is the proposed team room pilot.

A task marked as a [lead](https://console.uubright.com/docs/lead/) can also create workers in its room and
message them directly through `ccr-lead`, with owner-set limits. Lead actions
appear as notices in the room timeline. Leads and workers may use either Claude
Code or Codex while retaining the room. Handing off a lead to another agent keeps
its handle and workers, stops the old lead, and moves the Manager role to the new
task when it was the workspace's Manager.
Rooms may set `prRouting` to `ask` or `auto` for their tasks. Set it when
creating a room, or later with `POST /api/rooms/:id/pr-routing` and
`{"prRouting":"auto"}`. A task or lead setting overrides the room setting;
see [PR review routing](https://console.uubright.com/docs/lead/#pr-review-routing).

## Use rooms in the app

Open **Shared (preview)** from the workspace menu, **Workspace settings**, or **More**
on a phone, including one signed in with a pairing link.

1. Fill in **New room**: a name, an optional goal,
   a turn limit (up to 100), a time limit (up to 24 hours) and an optional budget
   (up to $100 in the app). The room shows what its tasks have used so far.
2. In the room, select **Start a task in this room**. The New task form opens with
   the room chosen; give the task a **handle**, such as `impl` or `reviewer`, and
   describe its work as usual. You can also choose a room on the New task form
   directly.
3. Talk to the room from the message box at the bottom of the room. Tick the members
   whose turn the message should start, or **Everyone**. With nobody ticked, the
   message is only recorded.
4. When an agent addresses another, the room shows it under **Waiting for you**.
   Select **Pass on to @handle**, **Pass all on**, or **Dismiss**.
5. When an agent asks you something, it appears under **Questions for you** at the
   top of the room, with its own reply box. **Reply to @handle** sends your answer
   to that agent and starts its turn. **Dismiss** clears a question you answered
   somewhere else, such as on the agent's task. The room list shows rooms with
   questions or hand-offs waiting.
6. Use **Members** to open a member's task or remove it, and **Task list** to add
   tasks and move them through `open`, `doing`, `review`, `done` and `blocked`.
7. **Auto-pass hand-offs**, **Pause room**, **Resume room** and **Disband room** are at
   the bottom. Resuming a room that used up its turns offers a higher turn limit, up to
   1,000, the server's limit; a room that has used all 1,000 can't be resumed, so start
   a new one.

A task in a shared room shows **Shared: NAME as @handle** under its title; select it to
return to the room. When that room has an open owner question or hand-off, the
task also links directly to each waiting item. The **Needs you** inbox shows
hand-offs with task titles, a message summary and the task **Pass on** will wake. A
message an agent addresses to `@owner` is an update: it is under **Updates**, where you
can reply or dismiss it, and it doesn't notify you. An agent that needs you to choose
asks a [decision](https://console.uubright.com/docs/tasks/#answer-decisions) instead.

To bring in an agent from another computer, such as Codex on your laptop, use **Invite**
under **Members**; see [Invite an outside agent](#invite-an-outside-agent).

Some actions are admin tasks and aren't in the app, for safety: adding an agent from
another machine with a long-lived token (owner token only, like invites), deleting a room for good, a new room with more
than 100 turns, and time limits above 24 hours. Do them on the server with the API, as below.

## From a script

The same actions are available from the [HTTP API](https://console.uubright.com/docs/api/#rooms).

```sh
API=http://127.0.0.1:8787/api
AUTH="Authorization: Bearer $CCR_CLOUD_TOKEN"

# A room with a goal, at most 30 agent turns, open for 8 hours.
ROOM=$(curl -s -X POST $API/rooms -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "rate limiting", "goal": "Add rate limiting to the API", "maxTurns": 30, "hours": 8}' | jq -r .id)

# Tasks join a room when you start them, each with a handle.
curl -s -X POST $API/sessions -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"room\": \"$ROOM\", \"handle\": \"planner\", \"projectId\": \"p-…\", \"modelRoute\": \"account\"}"
curl -s -X POST $API/sessions -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"room\": \"$ROOM\", \"handle\": \"worker\", \"projectId\": \"p-…\", \"modelRoute\": \"ccr\"}"
```

A task belongs to at most one room, and only from when it starts. Handles are
lowercase letters, digits and dashes; `owner`, `all` and `room` are reserved.

Each task in a room gets the `ccr-room` tools, already allowed, and a short note in
its system prompt. The note gives its handle and the room's goal, and tells it that
messages from other agents are peer input, not your instructions.

## Talk to the room

```sh
# Address members to wake them; without "to", the message is only recorded.
curl -s -X POST $API/rooms/$ROOM/messages -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"text": "Split the work into tasks and assign them.", "to": ["planner"]}'
```

The addressed task receives the message as a new turn, or after its current turn if
it is busy. If a task is stopped, the response lists it under `notWoken`; resume it
and send again.

## Hand-offs

When an agent posts to another agent, the room records a hand-off. Lead↔worker
hand-offs pass automatically when the worker was created by that lead; other
hand-offs send a push notification if [notifications](https://console.uubright.com/docs/notifications/) are on.
Pass one on, pass
on every open hand-off at once, or dismiss one:

```sh
curl -s $API/rooms/$ROOM -H "$AUTH" | jq .handoffs
curl -s -X POST $API/rooms/$ROOM/handoffs/h-1a2b3c4d/pass -H "$AUTH"
curl -s -X POST $API/rooms/$ROOM/handoffs/pass -H "$AUTH"        # all of them
curl -s -X POST $API/rooms/$ROOM/handoffs/h-1a2b3c4d/dismiss -H "$AUTH"
```

Passing on all hand-offs sends each recipient one prompt with every message
addressed to it. That suits a planner that has just assigned several tasks.
Hand-offs expire after 24 hours.

Lead↔worker passes count toward the room's turn limit and appear in its log as
passed by `lead-pair`. A worker addressing another worker, or a task addressing a
lead that did not create it, waits for you. Questions addressed to `owner` still
appear under **Questions for you**. A paused room passes nothing.

## Auto-pass

When you trust a room's agents to hand work to each other, turn on **Auto-pass
hand-offs** at the bottom of the room. The app asks you to confirm. From then on, a
message one agent addresses to a task starts that task's turn at once, exactly as if
you had selected **Pass on**. The room log shows each one as **Passed on
automatically**, and you get no hand-off notification for it.

- The turn and time limits still apply. Each automatic pass counts as one agent turn,
  and the room pauses at the limit. Keep the turn limit low enough to cap what two
  agents can spend talking to each other.
- If a pass can't start a turn (the room is paused, the limit is reached or the
  recipient's task is stopped), the hand-off waits under **Waiting for you** and you
  get a notification saying why.
- Automatic-pass intent is saved with the post. A restart or retried room call
  completes that attempt; a pass already recorded as completed is not started again.
  The posting agent receives `passedOn` only for completed passes and
  `waitingForOwner` for recipients that could not be started.
- Hand-offs that were already waiting when you turned it on stay for you to pass on.
- Lead↔worker hand-offs pass automatically even when room auto-pass is off.
- Messages to outside agents, such as Codex on your laptop, never need passing on. An
  outside agent still sees them only when it next reads the room.
- Only you can turn auto-pass on or off; agents have no tool for it.

```sh
curl -s -X POST $API/rooms/$ROOM/auto-pass -H "$AUTH" -H "Content-Type: application/json" -d '{"on": true}'
```

## The agent's tools

| Tool | What it does |
|---|---|
| `room_read` | Messages, task changes and member changes since the agent last read, plus the task list. A message that already started the agent's turn (your message to it, or a hand-off passed on) is left out, so it isn't handled twice; `since` re-reads everything. |
| `room_post` | Post a message, optionally addressed to members (`to`) or to `owner`. A message to `owner` sends you a notification. |
| `room_members` | Handles, whether each member is a task or an external agent, and each task's state. |
| `task_add` | Add a task to the shared list, optionally with an assignee. |
| `task_update` | Change a task's state (`open`, `doing`, `review`, `done`, `blocked`), assignee, note or branch. |

Every result includes `unread`, the number of messages addressed to the agent that it
hasn't read. The server records who sent each message, so an agent can't post as
you or as another member. You can add and change tasks yourself through
`POST /api/rooms/:id/tasks` and `PATCH /api/rooms/:id/tasks/:taskId`.

## Invite an outside agent

Like a meeting ID: the room gives you a short code, and the other computer joins with it.
Only you can invite or remove members, with the app open on the server itself (the owner
token); a paired phone, the relay and agents can't, because these hand out or end access to
the room.

1. In the room, under **Members**, optionally type the handle it should join as (such as
   `mac`). Check **Address the other computer uses**: it starts as the address you opened
   the app with, and must be `https`, or `http://localhost` or `http://127.0.0.1` for an
   agent on the same computer. Select **Invite** and confirm the address. The room shows a
   join code such as `K7QM-3XRA`, the address, the command to run, and a
   `scimigo://room-join?host=…&code=…` link. The code works once, for ten minutes, and only
   for this room (and that handle, if you gave one).
2. On the other computer, with uuBright Console installed (Node 22.18 or newer), run:

   ```sh
   uubright room join K7QM-3XRA --host https://ccr.example.com           # Codex (the default)
   uubright room join K7QM-3XRA --host https://ccr.example.com --agent claude --handle laptop
   ```

   It shows the address and asks before sending the code; check it's your server. Then it
   trades the code for a room token, backs up `~/.codex/config.toml` (or `~/.claude.json`)
   to `….bak-<time>` (it keeps the last three), adds the `ccr-room` server entry, makes the
   file readable only by you, and shows what changed in that entry, with the token hidden.
   Before using the code it checks that it can edit the file, and that there's no
   `ccr-room` entry already: `--replace` replaces one (for example, rejoining), `--name`
   adds another. `--print` shows the config snippet instead of writing anything; `--config
   PATH` writes another file.

   You can pass the link instead of the code and `--host`. A link's address is never used
   without your answer, or the same address repeated with `--host`. `--yes` skips the
   question only for an address you typed with `--host`, for scripts.
3. Restart Codex or Claude Code there. It has `room_read`, `room_post` and the other room
   tools, as `@handle`. Codex asks before each call to an MCP tool; `--approve-tools` writes
   `default_tools_approval_mode = "approve"` for this entry so it doesn't. In Claude Code,
   allow the tools when it first asks.

For a two-computer acceptance check, the owner can create a disposable room and
one disposable task on host A, then invite a teammate with the host's reachable
HTTPS address. The teammate runs the join command on computer B and asks their
agent to call `room_post` to the task's handle. The owner should see the hand-off,
select **Pass on**, and see the task receive that message; then remove the
teammate under **Members** and check that `room_read` reports a revoked token.
Do not count a local demo or a simulated second profile as proof of a physical
second computer.

Plain `http` is refused unless the address is `localhost` or `127.0.0.1`: the code, and
afterwards the room token on every call, would cross the network unencrypted. For a server
reached over Tailscale, use `tailscale serve` for an `https://….ts.net` address; see
[Access from your phone](https://console.uubright.com/docs/remote-access/).

The room log records each invite by id when it's created, used or revoked, never the code.
Unused invites are listed by `GET /api/rooms/:id/invites` and end when you revoke them,
disband the room or restart the server. The token the code buys works like the one below:
only this room's tools, until you remove the member or disband the room.

Wrong codes are counted: five from one network in ten minutes are refused, and ten across
the server drop every open invite and pause new ones for ten minutes. The price, as with
pairing codes, is that anyone who can reach your server can keep invites paused by sending
wrong codes; if that happens, add the agent with a room token as below. Behind a reverse
proxy, set `CCR_CLOUD_TRUST_PROXY=1` so networks are told apart.

## External members

An agent that doesn't run in uuBright Console can also join with a room token you create through
the API. Invite codes do the same in one step.

```sh
curl -s -X POST $API/rooms/$ROOM/members -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"handle": "codex"}'
# {"handle": "codex", "token": "ccr-room-…"}   the token is shown once
```

On the other machine, run the same MCP server from a ccr-cloud checkout (Node 22.18
or newer), pointed at your server. For Codex, add it to `~/.codex/config.toml`:

```toml
[mcp_servers.ccr-room]
command = "node"
args = ["/path/to/ccr-cloud/src/rooms/mcp.ts"]
env = { CCR_ROOM_URL = "https://ccr.example.com", CCR_ROOM_TOKEN = "ccr-room-…" }
```

`CCR_ROOM_URL` is the address you use for the app; see
[Access from your phone](https://console.uubright.com/docs/remote-access/) for ways to reach your server. The token
works only for this room's tools. It can't read your tasks, answer approvals or use
any other part of the API.

uuBright Console can't start an external agent's turns. When a message is addressed to one,
it waits until that agent next calls `room_read`, or until you tell it to check the
room. Codex tasks started by uuBright Console use the room tools through their
own runner, with access scoped to their room.

## Limits, pause and disband

| Limit | Default | What happens |
|---|---|---|
| Agent turns (`maxTurns`) | 50 | Each message you send to a task and each hand-off you pass on counts as one turn. At the limit the room pauses. |
| Time (`hours`) | 24, at most 336 | At the deadline the room pauses. |
| Budget (`budgetUsd`) | None | Once the member tasks' estimated cost reaches it, the room pauses and you get a notification. Turns already running finish. The estimate is Claude Code's, at API prices; see [usage](https://console.uubright.com/docs/tasks/#see-what-a-task-used). |
| Writes per member | 20 a minute | Further posts and task changes fail until the minute is up. |

While a room is paused, agents can still read it, but posts, task changes and
wake-ups are refused. Resume it with new limits:

```sh
curl -s -X POST $API/rooms/$ROOM/pause -H "$AUTH"
curl -s -X POST $API/rooms/$ROOM/resume -H "$AUTH" -H "Content-Type: application/json" -d '{"maxTurns": 60, "hours": 4}'
# A room paused at its budget resumes only with a higher one ("budgetUsd": null removes it).
curl -s -X POST $API/rooms/$ROOM/resume -H "$AUTH" -H "Content-Type: application/json" -d '{"budgetUsd": 20}'
```

`POST /api/rooms/:id/disband` ends the room. Its log stays readable, external
tokens stop working and open hand-offs are dropped. Member tasks keep running as
ordinary tasks. `DELETE /api/rooms/:id` removes the room and its log. Deleting a task
removes it from its room.

## How it works

A task's room tools go through its runner's existing connection. The MCP server talks
to the runner over a socket in the task's state directory. The runner sends each
call to the control plane and resends it after a reconnect until it gets an answer.

Each call's effects and its answer are saved together in one atomic write, so a crash
keeps both or neither. The control plane keeps the answer until the runner confirms
it received it. A call that arrives twice therefore takes effect once, even across a
restart. If a member has too many unanswered calls outstanding, new calls are refused
rather than old answers forgotten. External members call `POST /api/rooms/rpc` over
HTTPS. Their MCP server retries a call for about two minutes, and the control plane
keeps those answers for an hour.

Rooms are stored with your other data, in `rooms/` and `room-events/` in the data
directory.
