Before you start
An orchestrator, a crew, and a repository.
An orchestrator is a crew agent that plans a piece of work, hands each step to other crew agents, runs your checks, and opens a pull request for you to merge. It works in a git repository on a paired sidecar.
What it needs
The New task form lists anything missing and will not start until it is fixed:
- A connected sidecar, recent enough to start tasks, started with
--allow-shell. - Checks confirmed for the folder in Settings, Machine, Checks.
- An enabled orchestrator. Add the shipped one from Crew, Available, or switch Orchestrator on in any agent’s Policy section.
- At least one agent it can call, set in its Can call list.
Opening the pull request also needs the GitHub CLI, signed in, on that machine.
Confirm the checks
Checks are the named commands the orchestrator may run to test its work, such as test or lint. You confirm them for each folder, and it can run only those. If the checks file changes after you confirmed it, even by an agent, it reads as unconfirmed and nothing runs until you confirm it again.
Start
Hand it a task.
The New task form
Open it with + New task on Home, or New task on an orchestrator’s page. Fill in the Form tab, or use Paste to drop in a ticket and fill the form from it.
- Title and Ticket
- The title, and a ticket reference if there is one.
- Details
- Read by the orchestrator as context, not as instructions.
- Acceptance criteria
- What done means. Add as many as you need.
- Autonomy
- How much it may do without asking (below).
Start task runs it in the background. Its approvals appear on Home and in the orchestrator’s chat.
From a chat
An agent in a chat can draft a task for you as a card: the same fields, editable in place, with Start and Dismiss. It never starts by itself. A criterion the model proposed must be confirmed or edited by you before Start is offered, and a model’s draft is never set to Autonomous; only you can choose that.
Autonomy levels
- Interactive
- Asks at every checkpoint and reports after each step.
- HITL
Human in the loop - Asks before the plan, the push and the pull request. The default.
- Autonomous
- Plans, pushes and opens the pull request without asking.
| Interactive | HITL | Autonomous | |
|---|---|---|---|
| Submit the plan | Asks you | Asks you | Goes ahead |
| Push the branch | Asks you | Asks you | Goes ahead |
| Open the pull request | Asks you | Asks you | Goes ahead |
| Report after each step | Yes | No | No |
| Merge | Never, you do | Never, you do | Never, you do |
A task can use only the levels its orchestrator allows; the orchestrator’s own Autonomy setting is where you change that.
No level merges. A person always merges the pull request.
While it runs
What it does, and what it will not.
The run
- Confirms the task and its acceptance criteria.
- Lists the agents it can call and submits a plan, which you approve unless it is Autonomous.
- Hands each step to an agent with a delegated call, and reviews the result, within its limits on review rounds and delegations.
- Runs the confirmed checks.
- Creates a branch for the run, commits to it, pushes it, and opens a pull request against the default branch.
What it never does
- Merge. The pull request is yours.
- Force-push, or push the default branch.
- Start a branch over uncommitted changes, or in a folder another run is using.
- Commit to any branch but its own.
- Run anything as a check that you did not confirm.
Following it
Home’s Now band shows the task while it runs and keeps it there once it settles, with the reason it failed or the pull request it opened, until you dismiss it. Plan approvals appear there with Approve and Deny.