Automation reference

Orchestrator routes CI failures, review feedback, and merge conflicts with built-in rules. Project settings do not accept the retired reactions: configuration. See Migration before reusing an old YAML example.

For a step-by-step pull-request workflow, see Handle CI and review feedback.

What Orchestrator handles

Messages are signature-deduplicated, so an unchanged set of failures or comments is not sent on every poll. A changed failure set or changed unresolved feedback can produce a fresh nudge.

Recurring Automations are separate from these event rules. In the sidebar, create an automation with a project, prompt, agent, role, time zone, and schedule. You can inspect its run history, edit it, pause or resume it, and delete it. The CLI supports the same saved definitions:

ao automation create --project my-app --name "Daily checks" \
  --prompt "Run the project checks and summarize failures" \
  --cron "0 9 * * *" --timezone UTC
ao automation list --project my-app
ao automation runs <automation-id>
ao automation update <automation-id> --enabled=false

Choose one schedule format: a five-field cron expression or an RRULE, a calendar recurrence rule. Set the time zone with an IANA name, such as America/New_York.

Cron accepts numeric minute and hour fields, * for day and month, and supported weekday choices. It does not accept arbitrary ranges or steps. RRULE does not accept COUNT or UNTIL, or intervals faster than one minute.

The Automations page offers three template cards with editable starter prompts:

Choose a project with a GitHub repository and an agent with its own GitHub read access. Connecting GitHub to Orchestrator does not provide credentials to the agent. The prompts ask the agent to report missing access and stop. They request read-only reports in AO; the release-notes starter does not publish a release or claim merged work has deployed. These are prompt instructions, not a new sandbox or permission policy.

Review and edit the name, prompt, agent, and schedule before clicking Create automation. Selecting a card opens the standard creation dialog and saves nothing until you submit it. New automation opens a blank custom form. The prompt limit is 4,096 UTF-8 bytes. Template origin and its use-case category are recorded automatically; there is no purpose selector. Editing a definition keeps its original template identity.

CLI/API clients can optionally set templateId / useCase on creation (CLI: --template-id / --use-case). These fields only record intent; they do not load a starter prompt. The caller still supplies the prompt and schedule. Omitted fields default to custom / unknown. Update purpose with ao automation update <id> --use-case issue_triage; template origin cannot be updated. See product telemetry for the allowed categories and privacy details.

Automations run in the local daemon, so the computer must be awake and Orchestrator must be running. After a restart, Orchestrator runs at most three missed occurrences. The same automation will not start another run while its current run is active. Deleting an automation also deletes its run history.

To try an automation, create one in Automations with a short prompt and a schedule a few minutes ahead. Then open its run history and linked session. If it does not run, check the time zone, confirm the automation is enabled, and make sure Orchestrator stayed open and the computer stayed awake. Pause the automation before changing a schedule you are testing.

Project Cues save reusable instructions or exact shell commands for manual use. They do not run on a schedule. An agent Cue sends a prompt to an eligible session or starts a worker. A command Cue opens a fresh local terminal. Manage Cues in the project dialog and choose Run a cue from a session.

For example, create an agent Cue named Check tests with the prompt Run the focused tests and report failures, then choose Run a cue in a project session. If the session cannot accept a prompt, start a worker from the offered option or wait until the session can accept one.

A command Cue such as npm test runs that exact command in a new local shell. An agent does not review or interpret it, so check the command and working directory before running it.

Mode-aware delivery

Lifecycle messages go through the same session manager as user messages:

• Terminal UI sessions receive the message through their runtime.
• Chat sessions receive a native provider turn and persist it in the structured conversation.

Orchestrator does not run both controllers at once. A handoff between compatible interfaces drains or interrupts the old controller before committing the new one.

Notifications

The desktop notification center keeps alerts for input requests, pull requests ready to merge, merged pull requests, and pull requests closed without merging. Desktop toasts appear while Orchestrator is running. Marking an alert read keeps it in history; clearing one or all removes it from the center.

Paired phones can receive push notifications when notifications are allowed on the phone and the daemon can connect to the push service.

Orchestrator does not currently configure Slack, Discord, webhook notifiers, per-reaction retry budgets, or automatic merge from project config. Merge explicitly from the desktop or with:

ao pr merge <pr-number> --url <pr-url> --expected-head-sha <sha>

Reviews

Repository observation and Orchestrator reviewer agents are related but separate:

• The GitHub/GitLab observer watches a claimed pull request or merge request and records CI, review, and merge data.
• An Orchestrator review run starts a configured reviewer against a worker's pull request. Use Reviews in the desktop app or ao review trigger, ao review ls, and ao review cancel.

autoReview is a project default copied to new worker sessions. Each session also has its own toggle. Automatic review waits for an eligible pull-request revision and an idle worker. It does not merge the pull request or publish every workspace inspection as a review. See the agent catalog for reviewer support.