Skip to main content
Agent Orchestrator orchestrates end-to-end workflows from issue assignment to PR merge. Understanding these workflows helps you configure reactions and anticipate agent behavior.

​
Standard Workflow: Spawn → Work → PR → CI → Review → Merge

This is the most common workflow for feature development:
1
Human: Spawn Session
2
ao spawn my-project 123
3
What happens:
4
  • Tracker fetches issue details
  • Workspace creates git worktree + feature branch
  • Runtime creates tmux session
  • Agent launches with issue context
  • Session status: spawning → working
    • 5
    Agent: Work on Task
    6
    Agent autonomously:
    7
  • Reads relevant code
  • Writes implementation
  • Runs tests
  • Makes commits
    • 8
    Lifecycle state: working Activity state: active / ready
    9
    Agent: Create Pull Request
    10
    When work is complete, agent:
    11
  • Pushes branch to remote
  • Opens PR with gh pr create
  • Writes PR URL to metadata (via workspace hooks)
    • 12
    Lifecycle state: working → pr_open Event emitted: pr.created
    13
    CI: Run Checks
    14
    GitHub Actions (or other CI) runs tests.
    15
    Two paths:
    16
    Path A: CI Passes
    17
  • Session status: pr_open → review_pending
  • Event: ci.passing
  • Agent remains idle
    • 18
    Path B: CI Fails
    19
  • Session status: pr_open → ci_failed
  • Event: ci.failing
  • Auto-reaction triggered (if configured)
    • 20
    Reaction: Auto-Fix CI Failure
    21
    If ci-failed.auto: true:
    22
  • SCM fetches CI logs
  • Runtime sends logs to agent
  • Agent analyzes failure
  • Agent fixes code
  • Agent pushes new commit
  • CI runs again
    • 23
    Session status: ci_failed → pr_open Event: ci.fix_sent
    24
    If fix fails after retries:
    25
  • Event: ci.fix_failed
  • Human notified via escalation
    • 26
    Human: Review PR
    27
    Reviewer examines code.
    28
    Three outcomes:
    29
    Outcome A: Approved
    30
  • Session status: review_pending → approved
  • Event: review.approved
  • Check merge readiness
    • 31
    Outcome B: Changes Requested
    32
  • Session status: review_pending → changes_requested
  • Event: review.changes_requested
  • Auto-reaction triggered (if configured)
    • 33
    Outcome C: Just Comments
    34
  • Session stays: review_pending
  • Comments can be forwarded to agent (reaction config)
    • 35
    Reaction: Address Review Comments
    36
    If changes-requested.auto: true:
    37
  • SCM fetches review comments
  • Runtime sends comments to agent
  • Agent addresses feedback
  • Agent pushes new commits
  • PR updates, back to review
    • 38
    Session status: changes_requested → pr_open Event: review.comments_sent
    39
    If agent can’t resolve:
    40
  • Human notified after threshold
    • 41
    Check: Merge Readiness
    42
    When PR is approved + CI passes:
    43
  • Session status: approved → mergeable
  • Event: merge.ready
    • 44
    Check criteria:
    45
  • ✅ Review approved
  • ✅ CI passing
  • ✅ No merge conflicts
  • ✅ Branch up to date
    • 46
    Human: Merge PR
    47
    If approved-and-green.auto: false (default):
    48
  • Human gets notification
  • Human reviews and clicks merge
    • 49
    If approved-and-green.auto: true:
    50
  • Automatic merge via SCM plugin
    • 51
    Session status: mergeable → merged Event: merge.completed
    52
    Cleanup
    53
    After merge:
    54
    ao cleanup my-project --confirm
    55
    What happens:
    56
  • Runtime terminated
  • Workspace (worktree) deleted
  • Metadata moved to archive/

    • ​
    Auto-Reaction Workflows

    Reactions automate common interventions, reducing human toil.

    ​
    CI Failure Auto-Fix

    Trigger: ci.failing event
    Config key: ci-failed
    Default: Enabled with 2 retries     
    reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    message: |
      CI checks failed. Review the logs and fix the issue:
      
      {ci_logs}
    retries: 2
    escalateAfter: 30m
    Flow:
    1. Lifecycle Manager detects ci_failed status
    2. SCM fetches CI check details
    3. Runtime sends failure logs to agent
    4. Agent analyzes logs, fixes issue, pushes commit
    5. Lifecycle Manager detects PR updated → pr_open
    6. If CI fails again, repeat (up to retries times)
    7. If all retries exhausted, escalate to human
    The agent sees actual CI logs and error messages, not just “tests failed.” This gives it enough context to diagnose and fix most issues autonomously.

    ​
    Review Comments Auto-Response

    Trigger: review.changes_requested event
    Config key: changes-requested
    Default: Enabled with escalation     
    reactions:
  changes-requested:
    auto: true
    action: send-to-agent
    message: |
      Review feedback received:
      
      {review_comments}
      
      Please address these comments and push updates.
    retries: 1
    escalateAfter: 1h
    Flow:
    1. Lifecycle Manager detects changes_requested status
    2. SCM fetches review comments (including line numbers, file paths)
    3. Runtime sends comments to agent
    4. Agent reads feedback, updates code, pushes commits
    5. Lifecycle Manager detects PR updated → pr_open
    6. PR goes back to review
    7. If unresolved after 1 hour, escalate to human

    ​
    Automated Review Comments (Bug Bots)

    Trigger: automated_review.found event
    Config key: bugbot-comments
    Default: Enabled     
    reactions:
  bugbot-comments:
    auto: true
    action: send-to-agent
    message: |
      Automated review feedback from {bot_name}:
      
      {bot_comments}
      
      Please address these issues.
    Flow:
    1. SCM detects automated comments (bots, linters, security scanners)
    2. Event: automated_review.found
    3. Runtime sends bot feedback to agent
    4. Agent fixes issues flagged by bots
    5. Agent pushes fixes
    Supported bots:
    • GitHub CodeQL
    • Dependabot
    • ESLint bot
    • Security scanners

    ​
    Agent Stuck Detection

    Trigger: Agent idle beyond readyThresholdMs (default: 5 min)
    Config key: agent-stuck
    Default: Notify after 10 min     
    readyThresholdMs: 300000  # 5 minutes

reactions:
  agent-stuck:
    auto: true
    action: notify
    priority: urgent
    threshold: 10m
    message: |
      Agent {session_id} has been idle for {duration}.
      
      Check if it needs input or guidance.
    Flow:
    1. Lifecycle Manager polls sessions every 30s
    2. Agent plugin detects idle activity (last action > 5 min ago)
    3. If idle for 10 minutes total, event: session.stuck
    4. Notifier sends urgent notification
    5. Human attaches to session or sends guidance

    ​
    Agent Needs Input

    Trigger: Agent waiting for user response
    Config key: agent-needs-input
    Default: Immediate notification     
    reactions:
  agent-needs-input:
    auto: true
    action: notify
    priority: urgent
    message: |
      Agent {session_id} is waiting for your input.
    Flow:
    1. Agent plugin detects waiting_input activity state
    2. Lifecycle Manager updates status to needs_input
    3. Event: session.needs_input
    4. Notifier delivers urgent notification
    5. Human responds: ao send session-1 "Yes, proceed"
    6. Runtime delivers message to agent

    ​
    Merge Conflict Detection

    Trigger: PR has merge conflicts
    Config key: merge-conflicts
    Default: Send to agent     
    reactions:
  merge-conflicts:
    auto: true
    action: send-to-agent
    message: |
      Your PR has merge conflicts with {base_branch}.
      
      Please resolve the conflicts and push updates.
    Flow:
    1. SCM checks merge readiness
    2. If noConflicts: false, event: merge.conflicts
    3. Runtime notifies agent
    4. Agent pulls base branch, resolves conflicts, pushes

    ​
    Multi-Project Workflows

    Orchestrate work across multiple repositories.

    ​
    Cross-Repo Feature Development

    Scenario: Feature requires changes to backend and frontend.
    1
    Spawn Backend Session
    2
    ao spawn backend 123
    3
    Agent works on backend API.
    4
    Spawn Frontend Session
    5
    ao spawn frontend 123
    6
    Agent works on frontend UI.
    7
    Monitor Both Sessions
    8
    ao status
    9
    Dashboard shows both sessions in progress.
    10
    Coordinate Merges
    11
    When both PRs are approved:
    12
  • Merge backend first
  • Merge frontend after (depends on backend)
    • 13
    Or configure to wait for both:
    14
    reactions:
  approved-and-green:
    auto: false
    action: notify
    includeSummary: true
    15
    You get a summary of all ready PRs.

    ​
    Parallel Issue Batch

    Scenario: Clear backlog of 10 similar issues. 
    for issue in 120 121 122 123 124 125 126 127 128 129; do
  ao spawn my-project $issue
done
    Result:
    • 10 agents work in parallel
    • Each in its own worktree + tmux session
    • Each creates its own PR
    • Auto-reactions handle CI/review for all
    • You review and merge when ready
    Monitor: 
    ao status
# Or open dashboard: ao dashboard

    ​
    Custom Workflows

    ​
    Exploration Workflow (No Issue)

    Sometimes you want an agent to explore without a specific issue: 
    ao spawn my-project "Explore performance optimization opportunities"
    What happens:
    • No issue ID → agent gets free-form prompt
    • Agent explores codebase
    • Agent may or may not create PR
    • Session ends in done state (not merged)

    ​
    Orchestrator-Managed Workflow

    For complex workflows, spawn an orchestrator agent that manages other agents: 
    ao start                        # Start orchestrator agent
    The orchestrator agent:
    • Monitors project state
    • Spawns child agents for issues
    • Coordinates multi-agent workflows
    • Makes decisions about priorities
    • Reports summary to human
    Experimental: Orchestrator agents are a powerful pattern but require careful prompt engineering and monitoring.

    ​
    Review-Only Workflow

    Agent reviews code without making changes: 
    ao spawn my-project --agent reviewer "Review PR #456 for security issues"
    Flow:
    1. Agent fetches PR diff
    2. Agent analyzes code
    3. Agent posts review comments
    4. Session ends (no commits, no new PR)

    ​
    Incremental Workflow

    Agent works on large task incrementally: 
    ao spawn my-project 123 "Step 1: Add database schema"
    After first PR merges: 
    ao spawn my-project 123 "Step 2: Implement API endpoints"
    Each session creates a separate PR, building on previous work.

    ​
    Workflow Best Practices

    ​
    Reaction Configuration

    Start conservative: 
    reactions:
  ci-failed:
    auto: true          # Safe: CI failures are objective
    retries: 2
  
  changes-requested:
    auto: false         # Start with notify-only
    action: notify
  
  approved-and-green:
    auto: false         # Always review before merge
    action: notify
    Graduate to aggressive: After you trust the system: 
    reactions:
  changes-requested:
    auto: true          # Let agent address simple feedback
    escalateAfter: 1h
  
  approved-and-green:
    auto: true          # Auto-merge routine PRs

    ​
    Notification Routing

    Route notifications by priority: 
    notificationRouting:
  urgent: [desktop, slack]      # Agent stuck/needs input
  action: [desktop]             # Merge ready, decision needed
  warning: [slack]              # CI failures (may auto-fix)
  info: []                      # Don't notify for progress updates

    ​
    Session Monitoring

    Use the dashboard for overview: 
    ao dashboard
    Use CLI for quick checks: 
    ao status                       # All sessions
ao status my-project            # One project
    Set up notification channels:
    • Desktop: Immediate attention (urgent/action)
    • Slack: Team visibility (action/warning)
    • Webhook: Integration with your tools (all priorities)

    ​
    Agent Selection

    General purpose: claude-code (default)
    • Best for most tasks
    • Session resume support
    • Good at following complex instructions
    Fast iteration: codex
    • Quick responses
    • Good for small fixes
    Interactive: aider
    • Git-aware
    • Good at incremental changes
    Custom: Write your own agent plugin

    ​
    Workspace Strategy

    Most cases: worktree (default)
    • Shares git history
    • Fast and efficient
    • Agents see each other’s commits
    Complete isolation: clone
    • Separate git state
    • Higher disk usage
    • Use when agents might interfere

    ​
    Cleanup Cadence

    Clean up regularly to free resources: 
    ao cleanup --confirm             # All projects
ao cleanup my-project --confirm  # One project
    When to clean:
    • After PRs merge
    • After issues close
    • Weekly for stale sessions
    What to preserve:
    • Sessions in pr_open (may need revival)
    • Sessions in needs_input (waiting for you)
    • Sessions with unresolved work

    ​
    Troubleshooting Workflows

    ​
    Agent Not Creating PR

    Symptoms: Session stuck in working, no PR detected. Causes:
    1. Agent hasn’t finished work yet (check activity)
    2. Agent lacks GitHub permissions (gh auth login)
    3. Workspace hooks not set up (PR not written to metadata)
    Solutions: 
    ao send session-1 "Please create a pull request now"
# Or attach and check: ao attach session-1

    ​
    CI Keeps Failing

    Symptoms: Session cycles pr_open → ci_failed repeatedly. Causes:
    1. Flaky tests (non-deterministic failures)
    2. Agent misunderstanding failure logs
    3. Retries exhausted
    Solutions: 
    ao send session-1 "The test failure is due to [specific issue]. Please fix [specific thing]."
# Or disable auto-reaction and fix manually

    ​
    Review Comments Not Addressed

    Symptoms: Session stays in changes_requested. Causes:
    1. Comments require human judgment
    2. Agent doesn’t understand feedback
    3. Escalation threshold not reached
    Solutions: 
    ao send session-1 "The reviewer wants you to [clarification]. Please make that change."
# Or attach and help: ao attach session-1

    ​
    Agent Stuck

    Symptoms: Session in stuck state, no activity. Causes:
    1. Agent waiting for external resource
    2. Agent confused about next step
    3. Agent process died
    Solutions: 
    ao attach session-1              # Check what agent is doing
ao send session-1 "Please continue with [next step]"
# Or restore if dead: ao session restore session-1

    ​
    Next Steps

    Sessions

    Deep dive into session lifecycle and management

    Reactions

    Configure automatic reactions for your workflows

    Monitoring

    Set up monitoring and notifications

    Build docs developers (and LLMs) love

    Get started for freeTalk to us