Subagents

One agent can hand parts of a task to subagents on other harnesses and models. Each subagent is a real Cloudroom thread. It shows under its lead agent in the sidebar, and you can open it, read its work, or message it at any time.

Why mix models

No model is the best at everything. One plans well, another writes careful code, and another is fast and cheap. Subagents let one task use each model where it is strongest.

• Split the work: different parts of a feature go to different models at the same time.
• Get a second opinion: have 2 or 3 models review the same change, then compare.
• Save money: send simple, broad work to a cheaper model through Pi Agent and OpenRouter.

Start subagents

You don't need any commands. Tell your agent what you want, in plain words. Cloudroom's built-in instructions teach every agent how to start subagents.

Add team billing. Have Codex build the API, Sonnet the settings page, and Pi with DeepSeek the docs.

Review this pull request. Get a second opinion from Codex and a third from Pi with Kimi K3.

Find the worst bugs in this repo. Split it by folder and use a different model for each.

If you don't name the models, the lead agent picks them.

How it works

sequenceDiagram
  participant You
  participant Lead as Lead agent
  participant CR as Cloudroom
  participant Sub as Subagents
  You->>Lead: Give a task
  Lead->>CR: Start subagents, each with its own harness and model
  CR->>Sub: Start one thread per subagent
  Note over Lead: Keeps working
  Sub-->>CR: Finish
  CR-->>Lead: Message the lead each time one finishes
  Lead-->>You: Brings the results together

1. You give the lead agent a task.
2. It starts subagents and picks a harness and model for each one.
3. Each subagent runs as its own thread under the lead agent.
4. Cloudroom messages the lead agent each time a subagent finishes, so it never has to wait or check.
5. The lead agent checks the work and brings the results together.

Where subagents run

• Cloud threads: subagents run in the lead agent's sandbox and project folder. They can use Claude Code, Codex, or Pi Agent.
• Local threads: subagents run on your Mac with any installed harness. A Local thread can also start a subagent in the cloud. That subagent gets its own sandbox and starts from GitHub, so push your work first.

Steer and stop subagents

• Open a subagent: click it in the sidebar, under the lead agent's thread. Read its work or message it like any other thread.
• Let the lead agent manage them: it can check on, message, stop, and archive its own subagents.
• From a side chat: a side chat can read and message the main thread's subagents.

Built-in harness subagents

Claude Code and Codex have their own built-in subagents. Those run hidden inside one harness, on that harness's models, and don't show in Cloudroom. Cloudroom's instructions tell agents to start Cloudroom subagents instead. You can turn the built-in ones off in Settings → Providers → Claude Code and Codex.

For agents

Agents start subagents with the Cloudroom CLI. In a Cloud thread, the subagent runs in the same sandbox:

cloudroom thread spawn --provider pi --model openrouter/deepseek/deepseek-v4-pro --title "billing docs" --prompt "Write the billing docs."
cloudroom thread list
cloudroom thread output CHILD_ID
cloudroom thread tell CHILD_ID "Add a section on refunds."

In a Local thread, list a harness's models first, then start the subagent:

room-cli provider models codex
room-cli thread spawn --parent-self --project "$ROOM_PROJECT_ID" --provider codex --model MODEL --prompt "Build the billing API."

Pi models use provider/model, for example openrouter/deepseek/deepseek-v4-pro.

FAQ