Shared rooms (preview)
In the app, a room appears in one of two ways:
- The 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 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 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.
#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.
- 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.
- 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
implorreviewer, and describe its work as usual. You can also choose a room on the New task form directly. - 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.
- When an agent addresses another, the room shows it under Waiting for you. Select Pass on to @handle, Pass all on, or Dismiss.
- 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.
- Use Members to open a member's task or remove it, and Task list to add tasks and move them through
open,doing,review,doneandblocked. - 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 instead.
To bring in an agent from another computer, such as Codex on your laptop, use Invite under Members; see 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.
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
# 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 are on. Pass one on, pass on every open hand-off at once, or dismiss one:
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
passedOnonly for completed passes andwaitingForOwnerfor 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.
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.
- 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 behttps, orhttp://localhostorhttp://127.0.0.1for an agent on the same computer. Select Invite and confirm the address. The room shows a join code such asK7QM-3XRA, the address, the command to run, and ascimigo://room-join?host=…&code=…link. The code works once, for ten minutes, and only for this room (and that handle, if you gave one). On the other computer, with uuBright Console installed (Node 22.18 or newer), run:
SHELLuubright 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 laptopIt 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 theccr-roomserver 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 noccr-roomentry already:--replacereplaces one (for example, rejoining),--nameadds another.--printshows the config snippet instead of writing anything;--config PATHwrites 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.--yesskips the question only for an address you typed with--host, for scripts.- Restart Codex or Claude Code there. It has
room_read,room_postand the other room tools, as@handle. Codex asks before each call to an MCP tool;--approve-toolswritesdefault_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.
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.
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 onceOn 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:
[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 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. |
| 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:
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.