Per-role agents

AO has two session roles:

• A worker implements a focused task in an isolated workspace and may own pull requests.
• An orchestrator supervises a project, monitors sessions, and delegates implementation to workers.

Role and interface are separate choices. Either role can start in structured Chat or Terminal UI when its harness supports that interface.

Configure roles

Open the project settings in the desktop app and choose the worker and orchestrator agents. The CLI can set the initial agents while registering a project:

ao project add --path /absolute/path/to/repo \
  --worker-agent codex \
  --orchestrator-agent claude-code

For a full configuration replacement, the stored JSON shape is:

{
  "worker": {
    "agent": "codex",
    "agentConfig": {
      "model": "gpt-5.4",
      "permissions": "bypass-permissions"
    }
  },
  "orchestrator": {
    "agent": "claude-code",
    "agentConfig": {
      "model": "claude-opus-4"
    }
  }
}

Pass the object itself with ao project set-config <project-id> --config-json '<json-object>'; the flag does not read a file. This replaces the project config, so preserve any existing setup, rules, reviewers, or intake fields.

Start an orchestrator or worker

The desktop provides dedicated new-session and orchestrator flows. From the CLI:

ao spawn --project my-project --kind orchestrator \
  --name supervisor --mode chat

ao spawn --project my-project --kind worker \
  --name issue-42 --issue 42 --mode tui

--name is required and limited to 20 characters. --harness overrides the role's configured agent for one spawn.

Choose Chat or Terminal UI

• Use Chat for structured messages, provider activity, approvals, plans, changed files, usage, compaction, and rollback. Current native drivers cover Codex, Claude Code, OpenCode, and Droid.
• Use Terminal UI when you want the agent's native interface or a harness without native Chat support.

Compatible Claude Code and Codex sessions expose Open Chat or Open Terminal UI. Idle sessions switch directly. When work is active, AO asks whether to finish and drain it or stop and interrupt it before switching controllers.

Project rules

Use agentRules and agentRulesFile for worker instructions. Use orchestratorRules for supervision-specific guidance. These are stored in the typed project config and injected into the appropriate session role.