RFC: Agent teams in DreamCoder

This is an ongoing research RFC with no technical route chosen; start by reading the existing swarm and teammate paths in src/utils/swarm/backends/registry.ts, inProcessRunner.ts, and AgentTool.tsx, plus the server state added in #150. Compare the open questions and confirmed bugs #163 and #164 before proposing a direction. Done for this issue means recording findings and resolving the open questions; implementation work should be scoped in linked follow-up issues.

Status

Research. No technical route has been chosen. This issue collects findings and open questions and will be kept up to date as the research goes on.

Summary

Agent teams let several agents work on one goal: a lead splits the work, members carry it out in parallel, and they talk to each other along the way. DreamCoder already inherits Claude Code's experimental agent teams (behind Settings → General → Experimental, #134), but they are not verified end to end and the app has no dedicated view for them.

This RFC explores what a team mode in DreamCoder should be, and how members should run.

What DreamCoder has today

• Teams run in one process. The app drives the CLI in --print mode, which forces in-process teammates (src/utils/swarm/backends/registry.ts). Each teammate is isolated with AsyncLocalStorage (inProcessRunner.ts), so one team is one CLI process.
• Per teammate, in-process supports a model override but not a working directory. runWithCwdOverride exists (utils/cwd.ts) but only subagents use it; the teammate spawn path returns before isolation is handled (AgentTool.tsx), so every teammate runs in the lead's directory. A worktree per teammate needs this wired up first.
• In-process does not support a different provider. The API key and base URL come from the process environment (services/api/client.ts).
• TeammateExecutor is not in use. It is defined in utils/swarm/backends/types.ts with tmux, iTerm2 and in-process backends, but nothing calls getTeammateExecutor; spawning goes through its own handlers. It is a candidate seam, not a live one.
• Agent definitions already have isolation: worktree | remote in their frontmatter (loadAgentsDir.ts).
• The user can message a teammate from the app, but it only reads messages when idle. The desktop server writes the message into the teammate's mailbox (teamService.ts); in-process teammates check the mailbox only between turns. Claude Code's REPL has its own path (REPL.tsx onAgentSubmit).
• Bugs confirmed in a running app (at c49c1fb):
  • #163: teammates never claim tasks. They read tasks/<lead session id>/, while tasks are stored under tasks/<team name>/; three tasks stayed unowned for nine minutes.
  • #164: a teammate's permission request lands unread in the lead's inbox. The desktop shows no prompt and nothing denies it, so the teammate hangs.
  • #198: a teammate calling EnterWorktree changes the working directory of the whole process, so the lead and every other in-process teammate move into its worktree.
  • #199: whenever the lead's CLI process exits (Stop, /clear, restart, quitting the app), the team and task directories are deleted.
  • Not yet filed: after a page reload the team panel disappears and idle teammates show as completed; stopping the lead's turn ends the CLI and deletes the team folder with all teammates.
• Upstream has moved on since the fork (compat version 2.1.92): every session now has an implicit team and TeamCreate/TeamDelete are gone (2.1.178), and teammates inherit the lead's model and permission mode.
• #150 added server-side session state: versioned snapshots and patches broadcast to every client, a per-session model choice, first-wins permission replies, and CLI process generations. A team view can build on this.
• Cost of a CLI process: about 150–220 MB RSS and about 1% CPU when idle.

Landscape

• Subagent delegation is standard (OpenCode, Codex, Gemini CLI, Roo, Cline). Parallel worktree orchestrators are crowded (Conductor, vibe-kanban, claude-squad, Zed).
• Codex (MAv2): a tree of agents, all in one process, with six tools: spawn_agent, send_message, followup_task, wait_agent, list_agents and interrupt_agent (close_agent and resume_agent exist only in v1). Which version runs is chosen by a feature flag or the model's catalog entry; by default agents are spawned only when the user asks. An in-memory mailbox survives unloading idle agents (at most three children stay resident by default) but not a process restart. One provider per agent tree; the user cannot talk to a v2 child directly, and its approval prompts surface on the parent thread, labelled with their source. A tree-wide token budget is in development and off by default. No shared task list, no worktree per agent.
• Multica: an issue board where agents are teammates; a local daemon drives existing CLIs (Claude Code, Codex and others), one process per run. Assigning work to a squad wakes only the leader, which delegates with one @-mention comment and is re-woken by deterministic event rules, including when a member fails for good. Runs have explicit states and retries, deduplicated per issue, agent and comment thread. Agents talk only through issue comments. Runs on a GitHub repo, or in the local Parallel mode, each get a worktree branch; the default local mode serializes runs with a directory lock instead. Multica never merges. "Only a human moves work to done" is a prompt convention, and wrapped CLIs run with permission prompts bypassed.
• Paperclip: agents organised as a company, with an org chart, tickets, heartbeat wake-ups, budgets and approval gates; adapters drive external CLIs, one process per heartbeat run. The runtime checks out a ticket for the agent before starting it, so the model does not pick up work itself. Agents have no direct messages, only ticket comments, and @-mentions do not wake anyone. Agents share the project directory by default; a worktree per task is experimental and off. Wrapped Claude Code skips permission prompts by default, and most approval gates are off by default. A budget hard stop pauses the scope and opens an approval; with subscription billing cost is recorded as zero, so budgets do not apply.
• cc-haha: one session and process per member, each with its own provider and model, chosen on a plan review card that is always shown; a team workbench; a supervisor that restarts members; teammate permission prompts go to the lead. The runtime wakes members by task owner and dependencies; tasks without an owner are not assigned automatically. It reads the task list by team name, so it does not have the #163 mismatch. "Teammates do not claim tasks, so the lead does everything" was reported as cc-haha#1345 (closed). Cost is shown only as a notice before a run; there are no budgets. From v0.7.2 the code is under a non-MIT licence.
• Raven: a personal agent host that runs its own loop and also drives external CLIs (Claude Code, Codex, OpenCode) through ACP and other adapters. Delegation is one level deep: the host dispatches a dependency graph of subagents, which cannot delegate further and cannot message each other; results come back to the host as new turns. Its "self-evolving" features are offline or experimental and do not change the running host.
• Pattern: products that own their agent loop run agents in one process (Codex, OpenCode, Claude Code subagents). Products that wrap external CLIs run one process per agent or per run (Multica, Paperclip, cc-haha, claude-squad); Multica and Paperclip start a process for each run and let it exit.

Gaps DreamCoder could fill

• Teams that mix providers and models.
• A worktree per member, with the lead reviewing and merging.
• Task assignment by the runtime, using deterministic rules, instead of relying on the model to claim tasks.
• Cost per member, budgets, and auto-pause.
• Permissions per role.

Ideas under discussion

• Two kinds of member.
  • A process member is a full session with its own CLI process. The user can see it, talk to it, and resume it later.
  • An in-process member runs inside the lead's process. The app shows its output, and members can message each other, but the user cannot talk to it directly in the first version.
• Choosing where a member runs. By default, a member on the lead's provider runs in-process and a member on a different provider runs as its own process. An agent definition could force either, with a new frontmatter field next to isolation. A server-managed session backend would host process members; TeammateExecutor could become that seam once spawning actually goes through it.
• A team mode in the app. A task board (to do, in progress, in review, done) next to a combined activity stream of all members. Wake-ups follow server-side rules.
• Consent when one session starts another. Each request says whether the user asked for it, whether the agent is offering it, or whether the agent is proposing it on its own initiative. The server checks what it can verify itself: a turn woken by another session cannot start a session directly, and a new session never gets a higher permission mode than its parent.

Open questions

• Should a first version be in-process only, or include process members from the start?
• How are in-process and process members merged into one team view, and how do messages cross process boundaries?
• Should idle process members be unloaded and restored, as Codex does?
• How does the lead merge members' worktrees, and what happens on conflicts? Explored separately in #166 (isolated workspaces for members, with one provider interface and a shared merge layer; on hold since 2026-10-28 until the basic team flow works).
• How much of a task board is needed before this becomes an issue tracker?
• What budget and cost model applies when members use different providers?

Next steps

Research continues in this issue. Preparatory changes, such as letting a session run in its own process or share one, will get their own issues and link back here.