Agent teams

Status

Agent teams are an experimental preview and are off by default. The switch is Team execution preview in Settings, General, Orchestration (experimentalTeamExecution).

The switch controls starting new team work: new team conversations, new executions in an existing team conversation, and starting a saved team task. You can design and save teams while it is off. Work that is already open keeps running if you turn it off: you can still chat, delegate, retry, and stop.

Team definitions

A team is a saved roster. Every save creates a new, sealed revision; database triggers stop sealed revisions from changing. A team conversation stays pinned to the revision it started with.

• 1 to 12 members, each with a name, a free-text responsibility (up to 8,000 characters), and its own provider, model, effort, and Fast setting.
• Exactly one lead. Other members report to the lead or to another member, at most 3 levels deep. There are no fixed roles; the responsibility text is the role.

Discussion settings control how much members talk among themselves: ambient rounds (0 to 3) and peer follow-ups (0 to 2), both 0 by default.

Source: packages/protocol/src/orchestration.ts, packages/core/src/services/orchestration.ts

How a team runs

An execution is one burst of team work. Its coordination state is a journal stored as rows: the execution itself in team_executions, members in team_actors, every attempt in team_attempts with its prompt in team_attempt_prompts, messages and their delivery in team_messages, and file claims in team_claims. The team chat, workspaces, and integrations are stored in their own tables. Each change is validated and written with a revision number, so two writers cannot overwrite each other. A conversation has at most one open execution.

1. Start. OpenOrc checks that every member's provider is installed and signed in, creates the conversation, and opens an execution with a deadline.
2. Routing. Mentions choose recipients: @Name, @lead, or @all. A message without a mention goes to the lead.
3. Scheduling. The coordinator decides who runs next. The lead goes first, then members, then assignments, then turns nobody is waiting for. It keeps the number of running agents within the team's limit, with one extra slot for the lead when you are waiting for it. A child does not start while its manager's turn is running.
4. Delegation. The lead delegates by calling OpenOrc's task_create tool with a member and a request key, then calls team_wait and ends its turn, which frees its slot. The coordinator accepts only direct reports, one active assignment per member, and no more than the team's assignment limit. Delegation works only in Act mode; in Plan mode the same call saves a proposal.
5. Results. An assignment finishes with team_complete. Its result goes to its manager as a message, and its files are merged into the manager's folder before the manager's next turn. Participants in the shared conversation simply reply.
6. Completion. The execution completes when everyone is idle. After delegating, the lead must end each turn with team_wait or team_complete; otherwise it is marked as needing attention.

Hard limits stop runaway work: 1,000 attempts, 2,000 messages, and 2 MiB of message text per execution, plus the execution's time limit.

Source: packages/core/src/services/team-coordinator.ts, team-conversation.ts, packages/db/src/team-runtime.ts

Messages and delivery

Members talk through OpenOrc's team tools: team_say for the shared conversation, team_message between a manager and its direct reports, team_status to read the execution, team_history for older room messages, and team_claim to claim files. A mention of @lead in a member's reply wakes the lead.

A message is only marked delivered after the recipient's turn that carried it succeeds. When the recipient is busy, the coordinator tries to deliver it into the running turn:

• Codex receives it with turn/steer, with a 15-second limit.
• Claude receives it as a new stdin message, which it reads at its next tool boundary.
• OpenCode cannot receive messages mid-turn, so the message waits for the next turn.

The interface shows each message as Sent, Sending, Queued for next turn, or a failure such as "Couldn't confirm delivery". Delivery into a turn does not prove the agent acted on it. If a Codex steer times out, the recipient is stopped and marked as needing attention, because OpenOrc cannot tell whether the message arrived.

Workspaces

A team conversation has a lead workspace, and each assignment can have its own.

• Local mode, the default, uses your checkout as the lead workspace. The lead and every participant edit your files directly, and several can run at the same time. File claims made with team_claim are advisory; nothing stops two agents from editing the same file.
• Worktree mode builds the lead workspace in team-workspaces/ from a capture of your checkout, including uncommitted and untracked files.
• Assignments each get a detached worktree built from their manager's current files. Include files are copied and the project's setup script runs, with a 5-minute limit.

When an assignment finishes, its result is merged into its manager's workspace with a three-way tree merge in a scratch worktree, then written file by file. Each write checks that the file still has the content the merge expected, and every write goes through a temporary file and a rename. If the merge conflicts, the scratch worktree is kept so you can resolve it, then Retry or Accept.

Each turn's files are checkpointed under refs/openorc/teams/ in your repository, so a team conversation can be forked or restored from a checkpoint into a new folder. Moves switch the conversation between local and worktree mode and can be cancelled. Deleting a team conversation removes its folders, refs, and branches; branches are removed only if they are merged or pushed. A team conversation with saved tasks is hidden instead of deleted, so the tasks keep their history.

Source: packages/core/src/services/team-workspaces.ts, team-file-publication.ts, packages/git/src/team-transfer.ts

What each member sees

Each member's instructions are the usual conversation or task instructions, including the memory brief, followed by team rules: its responsibility, the roster, who it reports to, how to delegate and wait, how to claim files, and how to report results. Each turn's message adds:

• The member's assignment, up to 100,000 characters.
• Room messages the member missed, up to the newest 48 KiB.
• For the lead and conversation members: files colleagues have claimed, files they changed since the member's last turn, and files the member and a colleague both changed at the same time.
• Messages addressed to the member.

The lead and participants resume their provider sessions across executions. When a context is reset, the new session gets a seed of up to 64 KiB: the original instructions, directions, short results, and recent replies. History that does not fit in the seed is stored outside it, and the agent can read it with team_context. Recent replies that do not fit are dropped.

Restarts and recovery

After OpenOrc restarts, only turns that had already started need you. A member whose agent had started a turn is marked as needing attention, and so is its execution, because OpenOrc cannot tell what that turn did. You inspect it and decide whether to retry; retrying a turn that a restart interrupted does not count against the member's attempts. Turns that had not started yet are queued again and run on their own, and members that were waiting for a message keep waiting. Interrupted workspace operations are fenced and flagged.

The automatic stop at the deadline is set again at startup, so an execution already past its time limit is stopped, and no new turn starts after the limit.

OpenOrc sends notifications when an execution finishes, when something needs attention, and when a member waits for an approval or an answer. Stopping an execution, including by its deadline, does not notify.

Source: packages/core/src/services/team-attempt-recovery.ts, team-scheduler.ts

Not available yet

• Changing a team conversation's agent or model, or a member's settings. You can change the lead's effort and Fast mode from the composer, and Queue holds a message for its recipient's next turn.
• Preparing a team-owned task's worktree, removing it, or deleting the task from the task's own controls while its team conversation exists. The task's Start button works and routes the request through the team.
• Cancelling a failed fork, restore, or delete. They can only be retried, and while one is pending, the conversation is locked.
• Cleaning up kept folders and refs, except by deleting the whole conversation.
• Resolving a move conflict in place.
• Repositories with submodules, nested repositories, special files, and changes that turn a file into a folder or back.