Skip to main content
Harmony
Download

Orchestration

ExperimentalAvailable on: WindowsPresent in the build, unproven. May change or be removed.

How Harmony plans work, routes it to models, delegates it to agents, and verifies the result.

Orchestration is what turns a set of agent panes into something that can take a goal and come back with reviewed work. It is also the least settled part of the product.

WARNING

Modes in this section vary in maturity. Some are implemented and exercised; others are designed ahead of being proven end to end. Check feature status before depending on any of them.

The separation that explains everything

ComponentOwnsConsequence
Client (Desktop or TUI)Presentation and your decisionsClosing it does not stop a run
DaemonOrchestration state: plans, tasks, delegation, artifactsSingle durable writer
Session hostProvider processes and PTYsOwns what is actually executing

The TUI is a client, not the orchestrator. This is why a run continues when you close a window, and why two clients can watch the same run.

An execution route

"Which model ran this?" is not one question. A complete route is:

ElementMeaning
HarnessThe agent program being driven
ProviderThe vendor behind it
AccountWhich of your identities with that provider
ModelThe specific model requested
EffortReasoning depth, where the provider exposes it
Tool setWhat the agent is permitted to call
PlatformWhere the process runs
Billing classWhose money is spent, and under which plan

Any of these can differ between two steps of the same plan. A route shown before consent is a route you can refuse.

IMPORTANT

If projected cost or billing route cannot be determined, a run should block rather than proceed. Consent to spend you cannot see is not consent.

Modes

ModeWhat you approveMaturity
Plan onlyNothing runs; you get a planMost conservative
GuidedEach significant stepMiddle ground
AutomaticOne scoped consent for a reviewed planRequires trust in the plan

Start with plan-only against a real goal. Read what it proposes before you allow anything to execute.

The lifecycle

Orchestration lifecycleA goal becomes a plan, which is checked against policy, then routed to a provider and model per step. Work is delegated to agents in isolated worktrees, verified against evidence, integrated by an explicit decision, and only then complete. Two stages carry gates: routing blocks when projected cost or billing route cannot be determined, and verification requires evidence rather than an agent's claim of success. Consent is given once, after the plan and its routes are shown.YOU DECIDE HEREGoalPlanPolicyRouteDelegateWorkVerifyShipGATE — COSTGATE — EVIDENCEblocks if cost or billing route is unknownagent claims are not evidenceConsent once, after the plan and its routes are visible — not per action while tired.
Two stages are gates rather than steps. Routing is where cost becomes real; verification is where "done" is either earned or merely asserted.

Goal → plan → policy → route → delegate → work → verify → integrate → complete.

Two places deserve your attention:

  • Route, because that is where cost and provider choice become real.
  • Verify, because agent-reported success is not evidence.

Isolation

Delegated work runs in its own git worktree so parallel agents do not collide in the same files. See worktrees.

What not to assume

NOTE

Queued is not delivered. Delivered is not accepted. Accepted is not completed. A busy-looking fleet can be entirely blocked. Read task state rather than inferring from activity.