# Agent Teams

> A team is a replayable pipeline of agent roles drawn on a visual canvas: Start, one or more Agent steps (each with its own role, provider, model, step instructions and optional skills), an End, and connections between them.

- Area: Desktop, mobile and web
- Plans: All plans
- Last checked against the product: 2026-10-02
- Web page: https://agentsroom.dev/docs/teams

## What it does

A team is a replayable pipeline of agent roles drawn on a visual canvas: Start, one or more Agent steps (each with its own role, provider, model, step instructions and optional skills), an End, and connections between them. Run it on a backlog ticket or on a free prompt and the roles work one after another, each handing the next a structured payload (summary, changed files, touched areas, risks, test hints, flags). Connections can carry conditions on those flags, so a tester who reports `qaPassed = false` sends the work back to the developer, with a max-cycles guard against endless loops. Two unconditional connections out of one step run in parallel and rejoin on a common step. A "Wait for me" step parks the run on a question for you and resumes from your answer. A step can also carry a check command (`npm test`): its exit code writes the flag, overriding whatever the agent claimed.

Step instructions always win over the generic habits of a role: a step whose role is QA but whose instructions ask for tests to be written authors them, on the first cycle and on every later one, instead of falling back to "verify, do not write".

A team declares how its roles are embodied. In **Relay** mode (default) one console plays every role in turn and keeps the memory of the whole run. In **Team** mode every role is its own live agent; teammates start when first needed, catch up through shared notes and the git diff, and write to each other while they work. Team mode has a "Free-form conversation" switch: off, a teammate only writes to the roles its step points to; on, anyone writes to anyone. The roster every teammate reads says which roles are read-only, so a lead asks a reviewer what to verify instead of asking it to edit, commit or merge and collecting three refusals.

## Where to find it

- Inside a project, agents panel: **Add Team** ("Chain several agents into a pipeline you can replay") opens the **Agent Teams** modal with a **Run** tab and a **Configure** tab.
- The modal lists **Project teams** (committed with this project, shared across machines) and **Global teams** (available on every project). Five templates ship read-only: Build then verify, Spec build verify, Bug hunt, Release shield, Feature squad; **Duplicate to edit** gives you an editable copy. A template you do not want can be deleted like any other team, from the Configure list (**Delete**) or from the Run tab (**Delete team**), and it stays deleted at the next launch.
- On a backlog ticket, the **Team** field assigns a team instead of a single agent; the ticket then runs as a team run.
- In the Triggers panel, "Who runs it" offers **One agent** or **A team**, so a schedule or a webhook can start a whole pipeline. Such a launch obeys your quota rules, judged on the provider and account of the first step: a blocked launch starts nothing and notifies you ([Quota Rules](https://agentsroom.dev/docs/quota-rules.md)).
- Live runs appear as run boxes in the agents sidebar, with one line per step. A run alive on another machine of your account shows the same box here, titled "Team run on <device>" (steps, counter, machine), and on the phone as a card in the **Remote** screen of the project; see [Remote Fleet](https://agentsroom.dev/docs/remote-fleet.md).

## How to use it

1. **Add Team** > **New project team** (or **New global team**). Drag from the right handle of a node to the left handle of another to connect them; the **Agent** button adds a step, **Wait for me** adds a pause.
2. Select a step to set its **Agent** (inline, or **Use saved agent** to snapshot one of your saved agents), **Handoff mode** (Auto: detected when the agent finishes; Manual: you click **Hand off**), **Step instructions**, **Verify in browser**, **Read-only step**, **Own checkout**, **Check command** (with **Silence before cut-off (s)** and **Total budget (s)**) and **Skills**. A step also carries its own **Environment variables**: a step linked to a saved agent starts with that agent's block, so a first role that needs a token reaches its service instead of parking the run on a question. The team **Description** and the **Step instructions** are edited in the same composer as a backlog ticket: markdown toolbar, **Prompts** to insert a saved prompt of the open project, **Dictate**, **Save** to keep the text as a new prompt, and **Expand composer** to open the field full screen when the side panel is too narrow. Escape closes only the topmost layer (the full-screen composer or the agent configuration window), never the editor under it.
3. Select a connection to add a **Condition** (flag name, Equals, combined with AND / OR). The most specific matching connection wins; a connection without condition is the fallback. Every connection is one orthogonal wire with an arrow at its end, drawn in the theme's colours (the selected wire and the wire being drawn take the accent colour). A wire that goes back to an earlier step (QA to Dev) passes under the two cards and carries its label on that lower segment, so it never covers the label of the forward wire of the same pair; labels are always drawn above the cards. To move a wire, select it and drag its label chip (or the small round handle it shows when it has no label): a forward wire slides sideways, the other shapes up and down. Double-click the chip to go back to the automatic route ("Drag to move the wire, double-click to route it automatically again"). The moved position is saved with the team.
4. In **Team settings**, pick the **Execution mode** (Relay or Team), **Free-form conversation** and **Max cycles per node**.
5. The **Graph checks** panel lists blocking errors (missing Start or End, duplicate connections, two connections on the same condition, invalid fan-out) and warnings. Save is refused while errors remain.
6. **Run** tab > **Run this team**, or assign the team on a ticket and start it. Follow the run in its sidebar box: **Hand off** forces the next step, **Cancel** destroys the run's agents, **Finish** closes a run that reached End (its consoles close and the originating ticket moves to done). **Dismiss** (X) clears the box from the list. A finished run that still has live consoles (a blocked run keeps them on purpose, for inspection and **Loop back**) shows **Close consoles (N)** at the bottom of its box: it closes them in one click and keeps the run, with **Run again**, whereas the X also erases it. Cancelling while a step is finishing no longer starts the next step, and a console launched just before the cancel is closed with the others.

**Read-only step** ("This agent judges the work without changing it: no file edit, no git commit or push, no shell write") is the switch for a node that reviews, tests or gates: the CLI is launched without its write tools, so a reviewer cannot "fix" the code it judges or edit a test to make it pass, and two review nodes can no longer collide in the shared worktree. Reading, grep, git diff, tests, lint and every AgentsRoom tool (notes, messages, handoff, backlog, memory) stay open. The node shows a padlock badge, and the field says whether the chosen CLI enforces it or only states it in the prompt. The judging nodes of the shipped templates (QA and verify steps, the repro step of Bug hunt, QA and Security of Release shield, the tester of Feature squad) are read-only; templates already installed on a machine do not change.

**Own checkout** ("This step runs in its own disposable checkout, a snapshot of the workspace taken when it starts") is the isolation switch for steps that run at the same time or that measure: by default every step of a run works in one shared working tree, so two parallel steps that both edit a config or both run a coverage tool overwrite each other's files, and nothing reports it. With the box ticked, the step gets its own git worktree cut on a snapshot of the workspace (last commit plus the uncommitted work of the previous steps), refreshed every time the step starts again and removed with the consoles of its run. Every run gets its own folder under `.worktrees/` (named after the run and the step), and a run only ever removes its own checkouts: never one that a live run still works in, never one you locked with `git worktree lock`, and on Windows never one that a console or another program still uses (it is retried a little later, then left intact). Nothing written there reaches the run's branch, and the checkout starts without installed dependencies (the step installs what it needs), so it is for steps that review, probe or measure, not for the step that writes the change. The node shows a folder badge, the timeline says "runs in its own checkout", and the editor warns when two parallel steps still share the tree and one of them may write. If the checkout cannot be created, the run stops with the reason instead of quietly falling back to the shared tree. A parallel step that still shares the tree is told from its first turn which sibling steps write at the same time, and to re-read its files before relying on them; its handoff risks then list the files that changed in the tree during the fan-out (a line starting "Shared working tree:"), without saying which step wrote which, since git cannot tell.

A check command is cut off on **silence**, not on duration. **Silence before cut-off (s)** (default 120) is how long the command may print nothing at all before the runner kills it, and its clock restarts on every line printed, so a long suite that keeps reporting is never killed for taking long; **Total budget (s)** (default 3600) is the absolute cap that catches a command which never finishes, such as a test runner left in watch mode. A cut-off measures nothing, so it is not read as a failed gate: it writes the flag `checkTimedOut` next to the gate's own flag (a connection can route on it), and the timeline says "cut off (no output)" or "cut off (over budget)" instead of an exit code. The kill takes the whole process tree, so nothing keeps running behind it.

A step brief the console could not take is no longer abandoned: it is sent again every time that console is free, and the run box says so ("It is sent again automatically each time the console is free. Open the agent terminal to check on it, or cancel the run."). When your plan's cap of agents running at the same time is reached, the steps that were refused a console ("This agent did not start") start by themselves as soon as a slot frees, instead of waiting for a click. A live, idle console that ignores the brief four times is relaunched once on its own conversation and the brief is written into the new console, instead of the step staying stuck on "The step prompt could not be delivered to the agent."; the run timeline records the relaunch. A console that opened but whose CLI never started (its shell is back at the prompt) is no longer fed the brief in a loop: it is relaunched once, then the step is flagged as stalled with a hint to relaunch its agent or cancel the run. An agent opened by two panels at the same moment (a detached window and the main one) no longer leaves a hidden second console working in the project: the extra one is closed before it is wired to anything.

On a run blocked by the max-cycles guard, the run box now says "This team used all its cycles", names the last handoff ("Last handoff: <from> → <to>") and shows its report, so the QA's leftovers sent to the developer are readable without opening a console. **Add one cycle** / **Add two cycles** resume the run where it stopped: the blocked role receives that report and the whole team gets the extra cycles (since 2026-09-30, same buttons on the phone). **Loop back to <role>** stays for restarting from an earlier step: the click raises the ceiling by one for the whole graph, so the run carries on instead of re-blocking at the very first handoff. The guard stays, one extra cycle for one explicit click. A blocked run also keeps showing the consoles that are still alive, so the agent still working is visible instead of running out of sight.

A run started without a brief starts on its own: the first role is given its step instructions (or the handoff it received) as a first turn, instead of waiting on an empty prompt. A step whose console is alive but has never taken a turn is nudged again before any stall is declared.

After a restart of AgentsRoom, an interrupted run comes back on its own when agents may start at launch (see Settings): each role's console reopens on its previous conversation, with no **Resume** card to click per role, and the agent is told it is a restart and must carry on rather than redo the step. A step whose agent had already finished its turn (waiting for your answer, or stopped without handing over) is not re-entered at all: its console reopens on its conversation and the run moves on when you answer. A step that had already handed over is never re-entered on resume, even when the copy of the run held by the app was behind: the run's own log on disk decides. In Team mode, a teammate whose console died is relaunched the moment a message reaches it, with its memory, instead of being replaced by a blank agent after a wait. A parallel fan-out interrupted mid-way resumes where it was: finished branches keep their report, only the unfinished ones re-enter, and the source step is not replayed. A run parked on a question survives a restart too: the box "The team is waiting for you" still takes your answer after relaunching. When the run really moved on, that box disappears by itself; when it says "This run is no longer waiting: it was answered somewhere else, or it moved on." and cannot recover, a **Close this box** button clears it (the button only appears in that case, a box that still accepts answers cannot be hidden).

A run started on another computer signed in with your account is not a list of loose agents here: it is a team box "Team run on <device>" with its steps, its counter and the same banners (stop, question of a Wait for me step, mode). The box says "Hand-off, answers and cancel stay on <device>. From here you can open its consoles.": clicking a step or the card attaches its console, the controls stay on the machine that runs it. Since 1.179.0.

The run history of each team is in the modal (**Run history**). A stalled step (agent silent, prompt not accepted, agent waiting on its own prompt) is flagged with a hint on what to do.

A step whose flags match none of its connections (all of them conditional) no longer passes for a finished run: the run waits to be finished but is flagged "The step's flags matched none of its connections, so the run stopped before reaching its end.", and the "ready to close" notification is not sent. The agent is warned when it completes that way, and refused when its report names none of the flags its connections test (a forgotten or misspelled flag), so it can fix the report in the same turn. Completing the step again with the right flags resumes the run. In Team mode, a question sent with `expectsReply` is watched: a teammate that sits idle without answering is reminded, twice at most, then the run is flagged "An agent is waiting on an answer from <teammate> that never came." on the desktop and the phone. The agent that waits is no longer told to complete its step in the meantime, and a question goes to one teammate only. Since 2026-09-29.

A step completes once per cycle. If an agent signals "done" a second time after the run has moved on (a reviewer flipping its gate after a fix was agreed by message), the tool refuses the call and names the node the run is on and the remedy; when a signal still had to be discarded (a race with the transition, a branch that had already joined), the run timeline shows a line "Completion from <name> (cycle N) ignored: the run had already moved on", with the reason under it, so a hand-off that did not happen is visible instead of silent.

## Settings

- `autoLaunchAgentsAtStartup` (global, Settings > Terminal): when on, an interrupted team run resumes by itself at the next launch; off means nothing starts until you ask.
- `neverRestoreSessions` (global, Settings > Terminal, **Restore previous session** switched off) and `neverRestoreSession` (project override): when set, the consoles of a resumed run start blank instead of reopening their previous conversation. An agent whose own restore mode is "never" behaves the same.

- `backlogAutoCommitOnDone` (global, Settings > Backlog > **Commit automatically when work is done**; project override): when a run is closed with **Finish run** (button, phone or `team_finalize_run`), the files its agents changed are committed before the consoles close, and before the worktree auto-merge of its ticket. Cancelling a run never commits. Off by default. See [Backlog Task Board](https://agentsroom.dev/docs/backlog-task-board.md).
- `compactBetweenSteps` (team field, Teams window > **Team settings** > **Relay compaction** > **Compact the context before each next step**; Relay mode only; off by default): before each next step, the relay console runs its CLI's `/compact`, waits for it to finish, then receives the next step. The run's context is not lost: the step instructions, the handoff and the shared notes come back through the team tools after any compaction. Supported by Claude Code, Codex, Copilot, OpenCode, Grok, Mistral Vibe and Kimi; the other CLIs (Antigravity, Amp, Cursor, Aider and others with no manual compaction command) hand over without compacting. A step that relaunches its console (other provider, account or reasoning effort) starts fresh and is not compacted. Also settable with `teams_save({compactBetweenSteps: true})`. Since 2026-10-02.

## Agent tools (MCP)

- `teams_list`, `teams_get`: read the teams of the project and their graph. `teams_get` accepts `view: "structure"` (every node and connection, the two prompt fields of each agent step replaced by their size and a short preview) and `node` (one step in full, with the connections entering and leaving it): a large team with long personas no longer has to be pulled whole. Without `view`, the full team is returned when it fits in one tool result, the structure view otherwise.
- `teams_save`: create or update a team; accepts a dry run that validates without writing. To modify an existing team, incremental operations touch only what they name and leave every other step untouched: `nodePatches` (change fields of existing steps, `null` clears one), `addNodes` / `removeNodes` (removing a step drops its connections), `addEdges` / `removeEdges` (by id, or every connection between two steps) / `edgePatches`. They combine in one call, are validated like a full save, and `nodes` / `edges` still replace the whole graph when sent. A step read in structure view is refused as input, so the omitted prompts are never erased by accident. The answer also honours `view`. `readOnly` (a boolean on an agent node) is the only way to withhold write access from a step: there is no per-step permission mode or CLI flags. `ownWorktree` (a boolean on an agent node) gives the step its own disposable checkout; `teams_save` warns when parallel branches share the working tree and one of them may write.
- `teams_delete`: remove one team or many at once (`teamIds`), refused while one of them has a live run. Finding and clearing unused teams, one-off teams and the list's size limit: [Team cleanup](https://agentsroom.dev/docs/team-cleanup.md). Shipped templates are not reachable here: delete them from the Teams window.
- `team_finalize_run`: close a run sitting in awaiting-finalization, exactly like **Finish**. A run that has not reached End yet (a review step still to play) is refused, whoever calls it, and pointed to `team_cancel_run`.
- `team_cancel_run`: abort a run, exactly like the X on its run box.
- `capabilities_get`: returns the exact wiring contract the runner applies (node kinds, routing rules, validation rules, example graphs).

Inside a live run, every agent of the team gets a second set of tools, which only exist there: `team_get_context` (its own role, cycle, step instructions and the payload it received, never a colleague's; the step instructions are returned even after a context compaction, so an agent recovers its contract without reloading the whole team), `team_roster` (who is on the team and who it may write to), `team_read_notes` / `team_post_note` (the run's shared notes; a read returns the last 20000 characters by default, under a header giving the total size and the range shown; `maxBytes` changes the window, `from: "head"` reads the oldest notes first and `offset` pages through a long file, so the first notes of a long run stay reachable), `team_read_timeline`, `team_read_inbox`, `team_send` (and its older single-recipient form `team_ask`; a message sent with `expectsReply: true` tells the recipient to answer first, and the sender waits by ending its turn, since the reply lands in its console and starts its next turn; sends are budgeted per sender, per pair of roles and per ten minutes, and a duplicate of a message already sent is refused, which is a loop guard, not a failure to retry), `team_read_diff` (the git diff since the run started, or since the step started) and `team_complete_step`, which ends the step and hands over. A step that created its own git worktree for the ticket passes it as `workspaceCwd` on `team_complete_step`: the changed files, the diff and `team_read_diff` of the following steps are then read there (same repository only; a refused folder is reported in the next step's risks and the diff stays where it was). One flag name is reserved: `needsInput: true` does not route, it parks the run on the reporting step for a human (same answer box on desktop and phone, same notification as a **Wait for me** step, the step's summary shown as the question) before the step its other flags routed to starts; the answer then rides the handoff into that route. A route that already leads to a **Wait for me** step pauses once, not twice. Any other flag name is free. The size limits of a handoff are published in the tool itself: the summary is 40 to 1500 characters, risks and test hints are up to 20 items of 600 characters each, and flags up to 20 keys. One completion per cycle: once the run has routed on a step's flags, a second call from that node is refused, never re-routed; to change a gate after the fact, the node the run is on completes its own step so the graph loops back, then the original node completes again with the new flags.

`backlog_get` returns the live run of a ticket, including who started it (`triggeredBy`: the board, an agent over MCP with its id, the phone, a trigger, "Run again" with the source run, the Teams panel, or the add-agent modal). Runs written before 2026-09-15 carry no origin. A run that is not moving carries `stalled` (reason, step, since when, what it means and what to do, and for an unanswered question the teammate it waits on); `team_get_context` gives the same to the agents of the run. A run flagged `no-route` sits in awaiting-finalization but never reached its End: a coordinator must act on it, not finalize it blindly. Since 2026-09-29.

While a run is alive, its definition is frozen for agents: nodes, connections, max cycles, step instructions, skills, check command, role, provider and model are read-only through these tools, and a skill loaded by the run cannot be rewritten. You keep editing everything from the interface.

## Providers

All providers: each step picks its own provider and model, and the in-run coordination tools are exposed through MCP, so a team can mix CLIs. The run tools and the agent's identity are written into the configuration of every CLI, Mistral Vibe, Grok, Antigravity, Kimi and OpenCode included, so a run no longer stalls on a non-Claude node that answers "Unknown tool" or writes its brief into a file because it cannot hand over. OpenCode was the last CLI without these tools; fixed on 2026-09-15 (its generated config is per agent, so two OpenCode nodes of a fan-out never read each other's identity). Reasoning effort is pinned per step only for providers that expose it. A step that needs the browser (Verify in browser) relaunches its CLI with the browser tools when that step begins.

On a project offloaded to an SSH server ([Remote SSH Offload](https://agentsroom.dev/docs/remote-ssh-offload.md)), each step's console starts on the host and gets the run tools there for Claude Code and Codex only, the two CLIs the AgentsRoom tools are installed for on a host; a step on another CLI runs on the host without them.

**Read-only step** is enforced by the CLI itself on Claude Code (disallowed tools, which hold even in autonomous mode), Codex (read-only sandbox), Grok (deny rules), Antigravity (plan mode) and OpenCode (the built-in plan agent). On Mistral, Kimi, Amp, Copilot, Cursor, Aider and the other CLIs only the step prompt carries the rule, and the editor says so under the checkbox: pick one of the five enforced CLIs for a node that must not write. On Windows, a read-only Codex step could not run any command at all (not even reading a file); fixed on 2026-09-24, it reads code, runs `git diff` and the tests again.

## Mobile

Partial. The mobile companion can start a team on a project (picking the handoff mode, automatic or manual, manual by default) and then drive it with the same buttons as the desktop: **Hand off**, **Cancel**, **Finish**, **Run again**, **Close consoles (N)**, **Dismiss**, and going back to a role that already played. It shows the run with the progress of each step, opens the console of the agent currently working, answers a "Wait for me" question, and receives a push when a run parks, stalls or is ready to close. Answering a parked run from the phone goes through the same path as the desktop box, so it recovers a run lost by a restart the same way. A backlog ticket can be assigned to a team from the phone too (agent picker, **TEAMS** section), and starting it there runs the team exactly like the desktop board does (fixed on 2026-09-26: it used to run only one agent). The project's teams are listed from the **...** menu of the project screen, entry **Teams** (since 2026-10-01), and the list no longer comes back empty after the desktop restarts; when no desktop is connected the sheet says **Desktop not connected** ("Teams run on your desktop: open AgentsRoom there to list and launch them."). Not on the phone: the team editor, and writing a brief when starting a run. The run itself always executes on the desktop. A run alive on another machine of your account appears in the **Remote** screen of the project as a team card (title, machine, counter, steps, the question of a Wait for me step) with its consoles under it; tapping opens a console, the controls stay on that machine ("Hand-off, answers and cancel stay on <device>. From here you can open its consoles.").

## Limits

- A run is one shared git workspace (the project root, or the ticket's worktree): the next step sees the previous step's work through git. A team started by a trigger always uses the project root.
- The run's own state (notes, inbox, timeline, completion signals) is kept under the project root, not the worktree: a last step that removes the ticket's worktree and branch can still hand over and the run can still be finished. A run started before 2026-09-15 keeps its state under the worktree until it ends.
- One live run per ticket: starting a team on a ticket that already has a run in progress is refused from every surface (board, an agent's `backlog_start_next`, the phone, **Run again**, triggers) with "This ticket already has a team run in progress (run ..., team ..., workspace ...). Nothing was started: stop or finish that run before starting another one for the same ticket." Two local folders sharing one backlog still run a ticket in the folder it is started from.
- Parallel branches are one step deep and must converge on the same step. The console that drives the run is not handed a second branch at the same time: that branch gets its own agent, so no console is left playing two roles and unable to close either.
- Agents running at the same time are capped by your plan, across all your projects: 6 on Free, 9 on Plus, no cap on Pro. A team that hits the cap is not lost, its refused steps start as slots free up, but a large graph runs slower on a capped plan.
- Max cycles per node (default 3) blocks the run rather than looping forever; you can then finish, hand off once more, or cancel.
- A run reaching End waits for you to click **Finish**; agents of the run stay alive until you finish or dismiss it. Until you do, the step that ended the run can still send it back: a QA that finds one more defect after passing completes its step again and the run resumes where the new outcome leads, without a click from you.
- Templates cannot be edited in place; duplicate them. They can be deleted, and a deleted template does not come back at the next launch.
- Deleting the team behind a live run closes that run automatically.
- Teams are saved one at a time, so two machines editing different teams of the same project at once no longer overwrite each other, and a run always starts from the latest saved version of its team. A single very large team, or a project whose teams add up to a very large total, is refused with "This project's teams are too large to save. Nothing was saved: delete teams you no longer use, then try again." (fixed on 2026-10-01: before, a project with hundreds of teams could no longer save a new one at all). Since 2026-10-02 the **Configure** tab shows how full the list is and warns before the limit ([Team cleanup](https://agentsroom.dev/docs/team-cleanup.md)).
- A read-only step is a guard against accidents and role drift, not a security boundary: a determined shell command can still get around a deny list.
- Remote SSH project: the run works since 2026-09-18. The run itself stays on the desktop; the team tools of each step (roster, messages, step completion) reach it through the SSH tunnel back to this computer (the **Follows the agent to the host** list: "Team runs: the team tools of each step (roster, messages, step completion) reach the run through the SSH tunnel back to this computer, where the run itself stays"). Claude Code and Codex steps only, Node.js needed on the host; if the tunnel is down every run tool call fails naming it. The "new notes" reminder hook stays local.
- A run on another machine of your account is visible only while that machine answers, and a step can take a dozen seconds to change state on the other screen. Its controls (**Hand off**, **Cancel**, **Finish**, answering a question) stay on the machine that runs it. A project shared to you by another account does not announce its runs.
- On Windows, a step whose instructions or whose question to a **Wait for me** step were very long could never start, and the app blamed a broken CLI install. Fixed on 2026-09-21: the long parts travel in a file the agent reads (and `team_get_context` serves them again at any time), and a launch line still too long is named as the length limit, not as an install to redo.
- A run tool call whose answer never comes back fails after 90 seconds on Grok, Codex, Kimi and Mistral Vibe instead of leaving the step "working" for an hour and more (Grok's own default is 100 minutes); every run tool call is traced in the CLI's MCP logs.

## Common questions

- **Can I collapse a team run so it takes less room?** Yes. Click the run's header (or its chevron): the run folds into a single row like an agent, with the team's crest, the step it is on and its state ("Working…", "Waiting for you", "Done"). When the run needs you (a question, a handoff to confirm, **Finish run**) the folded row says "Waiting for you" with an orange badge; unfold it to answer. The fold is remembered per run on this computer. Same chevron on the phone.
- **Can I hide the agents of finished steps?** In Team mode, the agent tile under a finished step folds into its step row by default, unless that agent is working again or waiting for your answer. Use the arrows button on the step row to show or hide it.
- **Does closing a team commit its work?** Only with **Commit automatically when work is done** turned on (Settings > Backlog), and only when the run is finished with **Finish run**, not cancelled. Otherwise the files stay in the Changes tab for you to commit.
- **Can a relay run compact the context before the next role starts?** Yes: turn on **Compact the context before each next step** in **Team settings** (Relay mode). The console runs `/compact` between steps; CLIs without a manual compaction command skip it.
- **Relay or Team mode?** Ask what the run would fail on. Losing the thread: Relay (one session, nothing re-explained). Agreeing with itself: Team (the reviewer is not the author).
- **Do all agents start at once in Team mode?** No. A teammate starts the first time the graph reaches it or another agent writes to it, then stays alive for the run.
- **Can a team ask me something without ending?** Yes, route to a **Wait for me** step. The run parks, notifies you on desktop and phone, and resumes along that step's connection with your answer. A step can also escalate on its own by completing with the flag `needsInput: true`: the run pauses on that step, without any connection to draw.
- **`teams_get` is too big for my agent to read.** Ask for `view: "structure"` to get the topology without the prompts, then `node` for the one step you need; edit with `nodePatches` or `addNodes` / `addEdges` instead of resending the graph.
- **Where are teams stored?** Synced to your account: project teams follow the project, global teams follow you across machines. Templates are seeded locally on each machine. An agent asked to create a global team (`teams_save` with the global scope) on an account that never had one used to be refused for good, even after opening the Teams panel as the message suggested; fixed on 2026-09-24.
- **How do I stop my reviewer from fixing the code it reviews?** Tick **Read-only step** on that node. On Claude Code, Codex, Grok, Antigravity or OpenCode the CLI refuses the write; elsewhere the rule is in the prompt only.
- **Two parallel steps overwrote each other's files (a config, the coverage folder). How do I stop that?** Tick **Own checkout** on the steps that write or measure: each gets its own disposable copy of the workspace, and the step that authors the change keeps the shared tree. Read-only is not enough here, a reviewer running coverage writes to disk too.
- **Is this the same as Claude subagents?** No. Each step is a top-level agent with its own terminal you can talk to; a step may use subagents internally.
- **My reviewer called `team_complete_step` again with the gate set to true and nothing moved. Why?** The run had already routed on its first completion. Since 2026-09-15 the second call is refused with the way out: the node currently working completes its step, the graph loops back, the reviewer completes again.
- **My QA found another bug after the run ended, tried to send it back to the developer, and nothing happened.** Fixed on 2026-09-25. While the run waits for **Finish**, the step that ended it can complete again with the new outcome (for example "not passed"), and the run resumes on the developer by itself. Any other step is told that only you can send the run back, instead of being told its handoff was taken.
- **What is the "Completion ... ignored" line in the timeline?** A done signal the runner could not use: the run was already on another node, the parallel branch had already joined, or the signal arrived during a handoff. It shows the flags that signal carried.
- **Can I see who started a run?** Not in the run box. The origin is recorded in the run and returned by `backlog_get` for the ticket's live run.
- **My OpenCode node had no `team_send`, or on OpenCode 2.x its brief stayed typed in the console, or its read-only step never started.** Fixed on 2026-09-15 (run tools), then 2026-09-22 and 2026-09-23 for OpenCode 2.x: the brief is really submitted, even right after a CLI update, and a read-only step starts again.
- **After a restart of AgentsRoom the roles showed "Resume" cards, stopped talking to each other, or a question went unanswered.** Fixed on 2026-09-17 and 2026-09-19: a team console relaunched by the run reopens its previous conversation by itself, a dead teammate is relaunched with its memory when a message reaches it, an interrupted fan-out is rebuilt from the run's log, and the run resumes from the local disk before any contact with the server, so messages sent meanwhile are delivered. A teammate's message also reaches an agent that declared itself waiting, and an agent asking with `expectsReply: true` is told to end its turn, since the reply starts its next one.
- **A webhook started a team on my other computer and here I only see loose agents named by their session title.** Fixed in 1.179.0: the run now appears as a "Team run on <device>" box on every computer of the account and on the phone. Update both machines; an older host still announces loose agents.
- **A reviewer handed over files unrelated to the ticket, or two parallel steps in one tree changed files without saying so.** Fixed on 2026-09-22 and 2026-09-23: a step that created a worktree names it with `workspaceCwd` when it completes, and each parallel step knows who writes beside it, its handoff listing what moved during the fan-out. To really separate them, tick **Own checkout**.
- **Can I hand off or cancel a run from another machine?** Not today: the box says the controls stay on <device>. Open one of its consoles from here, or drive it from that machine or from the phone paired to it.
- **My team run on a Remote SSH project started its consoles on the server but nothing moved.** Fixed on 2026-09-18: the team tools now travel to the host and reach the run through the SSH tunnel. Steps must run on Claude Code or Codex, and the host needs Node.js; a manual reverse tunnel is no longer needed.
- **My check command finished fine but the gate was recorded as failed.** It was cut off by the old fixed five-minute budget. Since 2026-09-22 the gate is cut off on silence (default 120 seconds without a single line printed), with a total budget of 3600 seconds as a last net, both editable on the step. A cut-off is shown as "cut off", writes the flag `checkTimedOut` and no longer reads as a real failure downstream.
- **A step is stalled and says its brief could not be delivered to the agent.** Nothing to redo: the brief is sent again every time that console is free, without a new alert. Open the agent's terminal to see what is holding it, or cancel the run.
- **My team run said it was done, but the steps after the review never ran.** Fixed on 2026-09-29: the review step's flags matched none of its connections, and the run used to present that stop as a finished run. It is now flagged ("The step's flags matched none of its connections, so the run stopped before reaching its end."), the agent is warned or refused when it completes that way, and completing the step again with the right flags resumes the run. To make stopping there intended, add a connection without a condition.
- **Finishing, dismissing or closing the consoles of an old run deleted the checkout of the run I had just started, uncommitted work included.** Fixed on 2026-09-29: every run of a team used to get the same Own checkout folder. Each run now has its own, and a run only removes its own checkouts, never one a live run still uses or one locked with `git worktree lock`. On Windows a folder still in use is no longer emptied (which left git inside it pointing at the main project), so **Run this team again** no longer stops on "stale folder in the way". A checkout created before the fix keeps its old folder name (`team-run-...`): if one is left under `.worktrees/` once its runs are over, remove it with `git worktree remove`.
- **In Team mode an agent waited forever for a teammate's answer.** Fixed on 2026-09-29: the teammate is reminded when it sits idle without answering (twice at most), then the run is flagged "An agent is waiting on an answer from <teammate> that never came." on the desktop, the phone and in `backlog_get`. Open that teammate's console and ask it to reply with `team_send`, or answer the waiting agent in its own console. Messages sent to one agent at the same moment, or while it had just been handed another one, are no longer lost, and a message still waiting for a busy console when AgentsRoom quits is delivered after the restart.
- **Several steps say they never got a console.** Your plan's cap of agents running at the same time was reached ("This agent did not start"). They restart by themselves as slots free up; stop an agent you no longer need, or move to Pro for no cap.
- **In Team mode my teammates answered and the lead never picked it up.** Fixed on 2026-09-22: a reply now reaches a lead that is in the middle of its own step, instead of being held back until the step ended. Same day, a teammate woken by a message receives that message on Windows too.
- **The run stopped on the max cycles while the QA still had fixes for the developer.** Since 2026-09-30 the blocked run shows the last report and offers **Add one cycle** or **Add two cycles**: the developer gets the QA's report and the run carries on.
- **A blocked run left four idle consoles open. How do I free them without losing the run?** **Close consoles (N)** at the bottom of the run box (desktop and phone), added on 2026-09-24. The run stays in the list and can be run again. Since 2026-09-22, **Loop back to ...** on a blocked run raises the max-cycles ceiling by one for the whole team, so the run no longer blocks again straight away.
- **An agent closed my team run before the review step ran, or a finished run lost its Finish button.** `team_finalize_run` refuses a run that has not reached End since 2026-09-24. Since 2026-09-27 a run waiting at End keeps its **Finish** button and can be finalized by an agent, and the run box's button that moves the run to a step that never ran (a QA join, for example) now starts that step, after a confirmation, instead of doing nothing.
- **I edited my team (or an agent saved it with `teams_save`) and the next ticket still started on the old model.** Fixed on 2026-09-28: every start re-reads the saved team, from a ticket, a trigger, the phone or **Run again**. If the team cannot be found on this computer, the ticket starts on a single agent and, since 2026-09-27, the phone and the agent that asked are told so.
- **In Team mode every step started without its team tools and the run looped up to the maximum cycles.** Fixed on 2026-09-27: a console of a live run that lost its team identity at launch gets it back from the app before the CLI starts, for every CLI.
- **A wire runs across another card or hides a label. Can I move it?** Yes: select the wire, drag its label chip (or its round handle), and double-click it to return to the automatic route. Backward wires now pass under the cards on their own.

## Related

- [Agent Morphing](https://agentsroom.dev/docs/agent-morphing.md): the mechanism behind Relay mode.
- [Agent Messaging](https://agentsroom.dev/docs/agent-messaging.md): permanent agent-to-agent mail outside any run; Team mode uses the same idea inside a run.
- [Backlog Task Board](https://agentsroom.dev/docs/backlog-task-board.md): assign a team to a ticket.
- [Scheduled Tasks](https://agentsroom.dev/docs/scheduled-tasks.md) and [Webhook Triggers](https://agentsroom.dev/docs/webhook-triggers.md): start a team on a clock or an event.
- [Git Worktrees](https://agentsroom.dev/docs/worktrees.md): run a ticket's team in an isolated checkout.
- [Agent Delegation](https://agentsroom.dev/docs/agent-delegation.md): the one-call Dev to QA variant that needs no graph.
- [Remote Fleet](https://agentsroom.dev/docs/remote-fleet.md): the runs of your other machines shown as team boxes here and on the phone.
- [Remote SSH Offload](https://agentsroom.dev/docs/remote-ssh-offload.md): team runs on a project whose agents run on an SSH server.