> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.

# Reaction Configuration

> Auto-responses to CI failures, review comments, and agent events

Reactions are the core automation mechanism in Agent Orchestrator. They define how the system responds to events like CI failures, review comments, and agent state changes—automatically handling routine issues without human intervention.

## Reaction System Overview

When an event occurs (e.g., CI fails, review requested), the orchestrator:

<Steps>
  <Step title="Check Reaction Config">
    Looks up the reaction configuration for the event type
  </Step>

  <Step title="Auto-Handle">
    If `auto: true`, performs the configured action automatically
  </Step>

  <Step title="Escalate">
    If retries exhausted or timeout reached, escalates to human notification
  </Step>
</Steps>

**Push, not pull.** The human never needs to check on agents—the orchestrator notifies when judgment is required.

Source: `packages/core/src/lifecycle-manager.ts:422-498`

## Built-in Reactions

Agent Orchestrator includes 8 built-in reactions with sensible defaults:

### ci-failed

Triggered when CI checks fail on a PR.

```yaml theme={null}
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    message: "CI is failing on your PR. Run `gh pr checks` to see the failures, fix them, and push."
    retries: 2
    escalateAfter: 2  # Escalate to human after 2 failures
```

<ParamField path="auto" type="boolean" default="true">
  Enable automatic handling
</ParamField>

<ParamField path="action" type="enum" default="send-to-agent">
  What to do when CI fails:

  * `send-to-agent` — Send failure info to agent to fix
  * `notify` — Immediately notify human
</ParamField>

<ParamField path="retries" type="number" default="2">
  How many times to let the agent retry before escalating
</ParamField>

<ParamField path="escalateAfter" type="number">
  Escalate to human after this many failures
</ParamField>

### changes-requested

Triggered when a reviewer requests changes.

```yaml theme={null}
reactions:
  changes-requested:
    auto: true
    action: send-to-agent
    message: "There are review comments on your PR. Check with `gh pr view --comments` and `gh api` for inline comments. Address each one, push fixes, and reply."
    escalateAfter: 30m  # Escalate if not resolved in 30 minutes
```

<ParamField path="escalateAfter" type="string">
  Time-based escalation. Supports: `10m`, `1h`, `30m`
</ParamField>

<Info>
  The agent automatically fetches review comments and attempts to address them. Only escalates to human if it can't resolve within the time limit.
</Info>

### bugbot-comments

Triggered when automated review tools (linters, security scanners) leave comments.

```yaml theme={null}
reactions:
  bugbot-comments:
    auto: true
    action: send-to-agent
    message: "Automated review comments found on your PR. Fix the issues flagged by the bot."
    escalateAfter: 30m
```

Detects bot comments from common tools:

* GitHub Actions annotations
* ESLint reporters
* Security scanners
* Coverage reporters

### merge-conflicts

Triggered when the PR branch has merge conflicts with the base branch.

```yaml theme={null}
reactions:
  merge-conflicts:
    auto: true
    action: send-to-agent
    message: "Your branch has merge conflicts. Rebase on the default branch and resolve them."
    escalateAfter: 15m
```

<Note>
  The agent will attempt to rebase and resolve conflicts. Complex conflicts may require human intervention.
</Note>

### approved-and-green

Triggered when PR is approved by reviewers AND CI passes.

```yaml theme={null}
reactions:
  approved-and-green:
    auto: false  # Disabled by default — requires explicit opt-in
    action: notify
    priority: action
    message: "PR is ready to merge"
```

<Warning>
  **Auto-merge is disabled by default** for safety. Enable only if you have:

  * Comprehensive CI/CD tests
  * Required code review approval
  * High confidence in agent code quality
</Warning>

To enable auto-merge:

```yaml theme={null}
reactions:
  approved-and-green:
    auto: true  # Enable auto-merge
    action: auto-merge  # Change action from notify to auto-merge
```

See [Auto-Merge Configuration](#auto-merge-configuration) below for details.

### agent-stuck

Triggered when agent shows no activity for a duration.

```yaml theme={null}
reactions:
  agent-stuck:
    auto: true
    action: notify
    priority: urgent
    threshold: 10m  # Consider stuck after 10 minutes idle
```

<ParamField path="threshold" type="string" default="10m">
  Duration of inactivity before considering agent "stuck"
</ParamField>

Sends urgent notification to human to investigate.

### agent-needs-input

Triggered when agent asks a question or hits a permission prompt.

```yaml theme={null}
reactions:
  agent-needs-input:
    auto: true
    action: notify
    priority: urgent
```

Examples:

* "Should I proceed with this refactoring?"
* Permission prompt for file operations
* Confirmation needed for destructive changes

### agent-exited

Triggered when agent process exits unexpectedly.

```yaml theme={null}
reactions:
  agent-exited:
    auto: true
    action: notify
    priority: urgent
```

Causes:

* Agent crashed
* Out of memory
* Unhandled error
* Manual termination

### all-complete

Triggered when all spawned agents finish their work.

```yaml theme={null}
reactions:
  all-complete:
    auto: true
    action: notify
    priority: info
    includeSummary: true
```

<ParamField path="includeSummary" type="boolean" default="true">
  Include summary of all sessions in the notification
</ParamField>

Source: `packages/core/src/config.ts:215-278`

## Reaction Configuration Schema

All reactions support these fields:

<ParamField path="auto" type="boolean" required>
  Enable automatic handling. If `false`, the reaction is disabled.
</ParamField>

<ParamField path="action" type="enum" required>
  What action to take:

  * `send-to-agent` — Send message to agent to handle
  * `notify` — Send notification to human
  * `auto-merge` — Automatically merge the PR (only for `approved-and-green`)
</ParamField>

<ParamField path="message" type="string">
  Custom message to send to agent (for `send-to-agent` action) or human (for `notify` action).
</ParamField>

<ParamField path="priority" type="enum">
  Notification priority level:

  * `urgent` — Critical issues requiring immediate attention
  * `action` — Action required but not urgent
  * `warning` — Something to be aware of
  * `info` — Informational only

  Controls which notifiers receive the message (see [Notification Routing](/configuration/notifications#notification-routing)).
</ParamField>

<ParamField path="retries" type="number">
  How many times to retry `send-to-agent` before escalating to human.
</ParamField>

<ParamField path="escalateAfter" type="number | string">
  Escalation condition:

  * **Number:** Escalate after this many failures (e.g., `2` = after 2 failed attempts)
  * **String:** Escalate after this duration (e.g., `30m`, `1h`)
</ParamField>

<ParamField path="threshold" type="string">
  Duration threshold for time-based triggers (e.g., agent-stuck).

  Examples: `10m`, `30m`, `1h`
</ParamField>

<ParamField path="includeSummary" type="boolean">
  Include summary of all sessions in the notification (for `all-complete`).
</ParamField>

Source: `packages/core/src/types.ts:763-788`

## Global Reaction Configuration

Define default reaction behavior for all projects:

```yaml theme={null}
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 3  # More aggressive retry
    escalateAfter: 3
  
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 1h  # Give agent more time
  
  agent-stuck:
    auto: true
    action: notify
    priority: urgent
    threshold: 15m  # More lenient stuck detection
```

## Per-Project Reaction Overrides

Override global reactions for specific projects:

```yaml theme={null}
# Global defaults
reactions:
  approved-and-green:
    auto: false  # Auto-merge disabled globally
    action: notify

projects:
  # Trusted project: enable auto-merge
  frontend:
    repo: org/frontend
    path: ~/frontend
    reactions:
      approved-and-green:
        auto: true  # Override: enable auto-merge for this project
        action: auto-merge
  
  # High-risk project: more conservative
  payment-service:
    repo: org/payment-service
    path: ~/payment-service
    reactions:
      ci-failed:
        auto: false  # Override: disable auto-fix, always notify human
        action: notify
        priority: urgent
```

<Info>
  Per-project reactions **merge** with global reactions. You only need to specify the fields you want to override.
</Info>

## Auto-Merge Configuration

Auto-merge is the most aggressive automation option. Use with caution.

### Requirements for Auto-Merge

Before enabling auto-merge, ensure:

<Steps>
  <Step title="Comprehensive CI">
    Your CI pipeline includes:

    * Unit tests
    * Integration tests
    * Linting
    * Type checking
    * Security scanning
  </Step>

  <Step title="Required Approvals">
    GitHub branch protection requires:

    * At least one approval
    * Passing CI checks
    * Up-to-date branch
  </Step>

  <Step title="Agent Trust">
    You've validated agent quality on several PRs manually first.
  </Step>
</Steps>

### Enable Auto-Merge Globally

```yaml theme={null}
reactions:
  approved-and-green:
    auto: true
    action: auto-merge
    priority: info  # Notify after merge completes
```

### Enable Auto-Merge per Project

```yaml theme={null}
projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    reactions:
      approved-and-green:
        auto: true
        action: auto-merge
```

### Disable Auto-Merge (Default)

```yaml theme={null}
reactions:
  approved-and-green:
    auto: false  # Disabled (default)
    action: notify
    priority: action
    message: "PR is ready to merge"
```

With auto-merge disabled, you'll receive an "action" priority notification when PRs are ready, and merge them manually.

Source: `examples/auto-merge.yaml`

## Escalation Rules

Escalation determines when to notify a human after automatic handling fails.

### Retry-Based Escalation

Escalate after a number of failed attempts:

```yaml theme={null}
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 3
    escalateAfter: 3  # Notify human after 3 failed fix attempts
```

**Flow:**

1. CI fails → agent attempts fix #1
2. Still failing → agent attempts fix #2
3. Still failing → agent attempts fix #3
4. Still failing → **escalate to human** (urgent notification)

### Time-Based Escalation

Escalate after a duration:

```yaml theme={null}
reactions:
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 30m  # Notify human if unresolved in 30 minutes
```

**Flow:**

1. Review comments received → agent starts addressing
2. Timer starts (30 minutes)
3. If agent resolves within 30m → no escalation
4. If unresolved after 30m → **escalate to human** (urgent notification)

### Mixed Escalation

Combine both approaches:

```yaml theme={null}
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 5
    escalateAfter: 1h  # Escalate after 5 failures OR 1 hour, whichever comes first
```

## Custom Reaction Messages

Override default messages:

```yaml theme={null}
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    message: |
      CI checks are failing. Please:
      1. Run `gh pr checks` to see failures
      2. Run tests locally: `pnpm test`
      3. Fix the issues and push
      4. Verify CI passes
    retries: 2
```

Custom messages for notifications:

```yaml theme={null}
reactions:
  approved-and-green:
    auto: false
    action: notify
    priority: action
    message: "🎉 PR approved and CI green! Ready to merge: {{prUrl}}"
```

<Note>
  Messages support template variables like `{{prUrl}}`, `{{sessionId}}`, `{{projectId}}`.
</Note>

## Disabling Reactions

Disable a reaction by setting `auto: false`:

```yaml theme={null}
reactions:
  changes-requested:
    auto: false  # Disable automatic handling
    action: notify  # Always notify human immediately
    priority: action
```

When disabled, the orchestrator immediately notifies humans instead of attempting automatic handling.

## Testing Reactions

Test your reaction configuration:

```bash theme={null}
# Spawn an agent on a test issue
ao spawn my-app TEST-123

# Watch the dashboard
ao status

# Trigger events manually:
# - Push a failing commit (to trigger ci-failed)
# - Request changes on the PR (to trigger changes-requested)
# - Approve the PR (to trigger approved-and-green)
```

Monitor logs to see reaction behavior:

```bash theme={null}
# Check orchestrator logs
tail -f ~/.agent-orchestrator/logs/orchestrator.log
```

## Complete Example

A production-ready reaction configuration:

```yaml theme={null}
reactions:
  # Auto-fix CI failures with retries
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 3
    escalateAfter: 3
  
  # Auto-address review comments with timeout
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 45m
  
  # Auto-fix bot comments
  bugbot-comments:
    auto: true
    action: send-to-agent
    escalateAfter: 30m
  
  # Auto-resolve merge conflicts
  merge-conflicts:
    auto: true
    action: send-to-agent
    escalateAfter: 20m
  
  # Notify when ready (auto-merge disabled for safety)
  approved-and-green:
    auto: false
    action: notify
    priority: action
    message: "PR ready to merge"
  
  # Notify when agent is stuck
  agent-stuck:
    auto: true
    action: notify
    priority: urgent
    threshold: 12m
  
  # Urgent notification when agent needs input
  agent-needs-input:
    auto: true
    action: notify
    priority: urgent
  
  # Urgent notification on agent crash
  agent-exited:
    auto: true
    action: notify
    priority: urgent
  
  # Summary when all done
  all-complete:
    auto: true
    action: notify
    priority: info
    includeSummary: true
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Notifications" icon="bell" href="/configuration/notifications">
    Configure how reactions notify you via Slack, Discord, etc.
  </Card>

  <Card title="Projects" icon="folder" href="/configuration/projects">
    Set up per-project reaction overrides
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.