AO: Agent Orchestrator

Documentation

Lifecycle automation

Practical guidance for AO's built-in CI, review, conflict, and notification behavior.

Current AO ships lifecycle policy rather than a configurable reaction recipe engine. Do not add reactions: to project configuration: unknown fields are rejected, and legacy keys such as auto, retries, escalateAfter, threshold, and auto-merge have no current consumer.

Let AO route repository feedback

Claim the pull request to the worker that should respond:

ao session claim-pr <pr-number-or-url>
# From outside the worker, target it explicitly:
ao session claim-pr <session-id> <pr-number-or-url>

The one-argument form uses AO_SESSION_ID and is preferred inside a worker session.

AO then routes failing checks, requested changes, unresolved comments, and eligible merge conflicts to that session. Delivery is mode-aware, so the same workflow works for structured Chat and Terminal UI.

Avoid duplicate nudges

AO stores or remembers signatures for observed feedback. It sends again when the meaningful content changes, not merely because another poll happened. This keeps long-lived agent sessions from receiving the same CI failure or review body repeatedly.

Know what requires a human

The notification center provides durable read/unread history for:

  • a session waiting for input;
  • a pull request ready to merge;
  • a merged pull request;
  • a pull request closed without merging.

Click a notification to open its session or PR context. Desktop toasts supplement the durable history while the app is running.

Intervene manually

Send a focused instruction to a session from its Chat composer or Terminal UI. The CLI equivalent is:

ao send --help

Use the help output for the current target and message flags. For an independent code review, use ao review trigger <worker-session-id>.

Merge is always an explicit action:

ao pr merge <pr-number>

Switch interfaces when useful

For compatible Claude Code and Codex sessions, use Open Chat or Open Terminal UI. AO preserves the session and worktree, drains or interrupts active work according to your choice, and commits only one controller at a time.

A first Terminal UI → Chat switch preserves provider-native context where supported, but it does not convert old terminal screen output into structured Chat cards.

See Lifecycle automation configuration for the current event and notification reference.