Your first orchestration run
Delegate work across more than one agent, and understand what is proven versus what is still being built.
WARNING
Orchestration is the least settled part of Harmony. Some modes are implemented and exercised; others are designed ahead of being proven end to end. Treat this page as a guided tour of something under construction, not a stable workflow. Feature status records the current state of each piece.
Outcome: one goal planned and delegated across more than one agent, with the plan visible before anything runs.
Prerequisites
- A completed single-agent session
- At least one provider connected
Do not start here. If a single agent session does not work reliably on your machine, orchestration will not either, and it will be much harder to tell why.
What orchestration actually is
Three things stay separate, and confusing them causes most of the trouble:
| Component | Owns |
|---|---|
| The client (Desktop or TUI) | Showing you the run and taking your decisions |
| The daemon | Orchestration state — plans, tasks, delegation, artifacts |
| The session host | Provider processes and PTYs |
The client is a view. Closing it does not stop a run.
1. Start with a plan, not an execution
Ask for a plan before authorising work:
/orchestrate Migrate the config loader to the new schema
Expected result: proposed steps, a model chosen per step with a stated reason, and projected cost and billing route shown before you consent.
IMPORTANT
If cost or billing route cannot be determined, the run should block rather than proceed. Consent to spend you cannot see is not consent.
2. Read the plan before consenting
Check three things:
- Scope — do the steps stay inside what you asked for?
- Route — is each step going to a provider and model you intend to pay for?
- Isolation — will parallel work happen in separate worktrees?
3. Consent once, scoped
Approve the plan as a unit. One scoped consent for a reviewed plan is safer than approving many individual actions while tired.
4. Watch delegation
Delegated work runs against its own worktree so agents do not collide in the same files. See worktrees.
Verify:
nala tasks list
NOTE
Queued is not the same as delivered, and delivered is not the same as completed. A delegated task can sit queued while everything looks busy. Read the task state, not the activity.
5. Verify before integrating
Treat agent-produced work as a pull request from a stranger who is very confident. Read the diff, run the tests, then integrate.
Common recovery
| Symptom | Where to go |
|---|---|
| Plan never appears | Provider problems |
| Run appears stuck | Check task state, then daemon problems |
| Agents conflict in the same files | Confirm worktree isolation was used |
| Cost was not shown | Do not consent; report it |