> ## 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.

# Configuration Examples

> Real-world configuration examples and use cases for Agent Orchestrator

This page provides practical configuration examples for common use cases. Copy and customize these examples to get started quickly.

## Quick Start

Copy an example and customize:

```bash theme={null}
cp examples/simple-github.yaml agent-orchestrator.yaml
nano agent-orchestrator.yaml  # edit as needed
ao spawn my-app ISSUE-123
```

## Simple GitHub Setup

Perfect for getting started with a single GitHub repository.

<Accordion title="simple-github.yaml">
  **Use this if**:

  * You're working on a single GitHub repository
  * You want to use GitHub Issues for task tracking
  * You want the simplest possible setup

  ```yaml theme={null}
  # Minimal setup for a single GitHub repo with GitHub Issues
  # Perfect for getting started quickly

  dataDir: ~/.agent-orchestrator
  worktreeDir: ~/.worktrees

  projects:
    my-app:
      repo: owner/my-app
      path: ~/my-app
      defaultBranch: main
  ```

  <Info>
    This minimal configuration uses all defaults: tmux runtime, claude-code agent, worktree workspace, and desktop notifications.
  </Info>
</Accordion>

## Linear Integration

Integrate with Linear for issue tracking and team management.

<Accordion title="linear-team.yaml">
  **Use this if**:

  * Your team uses Linear for project management
  * You want agents to update Linear ticket status
  * You need custom agent rules per project

  ```yaml theme={null}
  # Linear integration with custom team
  # Requires LINEAR_API_KEY environment variable

  dataDir: ~/.agent-orchestrator
  worktreeDir: ~/.worktrees

  projects:
    my-app:
      repo: owner/my-app
      path: ~/my-app
      defaultBranch: main

      # Linear tracker integration
      tracker:
        plugin: linear
        teamId: "2a6e9b1b-19cd-4e30-b5bd-7b34dc491c7e"

      # Custom rules for agents
      agentRules: |
        Always link Linear tickets in commit messages.
        Run tests before pushing.
        Use conventional commits (feat:, fix:, chore:).
  ```

  <Steps>
    <Step title="Get your Linear API key">
      Visit [Linear API Settings](https://linear.app/settings/api) and create a new API key.
    </Step>

    <Step title="Set environment variable">
      ```bash theme={null}
      echo 'export LINEAR_API_KEY="lin_api_..."' >> ~/.zshrc
      source ~/.zshrc
      ```
    </Step>

    <Step title="Find your team ID">
      Your team ID is visible in your Linear workspace URL or via the API.
    </Step>
  </Steps>
</Accordion>

## Multi-Project Setup

Manage multiple repositories with different trackers and notification routing.

<Accordion title="multi-project.yaml">
  **Use this if**:

  * You're managing multiple repositories
  * Different projects use different trackers (GitHub Issues vs Linear)
  * You want Slack notifications in addition to desktop
  * You need different rules per project

  ```yaml theme={null}
  # Managing multiple projects with different trackers
  # Shows how to configure multiple repos with different settings

  dataDir: ~/.agent-orchestrator
  worktreeDir: ~/.worktrees

  defaults:
    runtime: tmux
    agent: claude-code
    workspace: worktree
    notifiers: [desktop, slack]

  projects:
    frontend:
      name: Frontend
      repo: org/frontend
      path: ~/frontend
      defaultBranch: main
      sessionPrefix: fe

      tracker:
        plugin: github

      agentRules: |
        Use TypeScript strict mode.
        Follow React best practices.
        Always run `pnpm test` before pushing.

    backend:
      name: Backend API
      repo: org/backend
      path: ~/backend
      defaultBranch: main
      sessionPrefix: api

      tracker:
        plugin: linear
        teamId: "your-team-id"

      agentRules: |
        All endpoints require auth middleware.
        Add OpenAPI docs for new routes.
        Run `pnpm test` and `pnpm lint` before pushing.

  # Slack notifications (requires SLACK_WEBHOOK_URL)
  notifiers:
    slack:
      plugin: slack
      webhook: ${SLACK_WEBHOOK_URL}
      channel: "#agent-updates"

  # Route notifications by priority
  notificationRouting:
    urgent: [desktop, slack]
    action: [desktop, slack]
    warning: [slack]
    info: [slack]
  ```

  <Note>
    Set `SLACK_WEBHOOK_URL` environment variable with your Slack incoming webhook URL.
  </Note>
</Accordion>

## Auto-Merge Configuration

Maximum automation with automatic PR merging when approved and CI passes.

<Accordion title="auto-merge.yaml">
  **Use this if**:

  * You trust your agents and CI pipeline
  * You want maximum automation
  * You want agents to handle routine failures autonomously
  * You want escalation only when agents get stuck

  ```yaml theme={null}
  # Aggressive automation with auto-merge
  # Automatically merges approved PRs with passing CI

  dataDir: ~/.agent-orchestrator
  worktreeDir: ~/.worktrees

  projects:
    my-app:
      repo: owner/my-app
      path: ~/my-app
      defaultBranch: main

      # Enable auto-merge for this project
      reactions:
        approved-and-green:
          auto: true # Automatically merge when PR is approved and CI passes
          action: auto-merge

  # Global reactions
  reactions:
    # Auto-retry CI failures up to 3 times
    ci-failed:
      auto: true
      action: send-to-agent
      retries: 3

    # Auto-address review comments
    changes-requested:
      auto: true
      action: send-to-agent
      escalateAfter: 1h # Notify human if not resolved in 1 hour

    # Notify when agent is stuck
    agent-stuck:
      threshold: 10m
      action: notify
      priority: urgent
  ```

  <Warning>
    **Only enable auto-merge if**:

    * ✅ You have comprehensive CI/CD tests
    * ✅ You require code review approval
    * ✅ You trust your agents to write correct code
    * ✅ You want maximum automation

    Start with `auto: false` and enable after building confidence.
  </Warning>
</Accordion>

## Codex Integration

Use GPT-4/Codex instead of Claude Code as your AI coding assistant.

<Accordion title="codex-integration.yaml">
  **Use this if**:

  * You prefer GPT-4/Codex over Claude
  * You need agent-specific configuration
  * You're evaluating different AI coding assistants

  ```yaml theme={null}
  # Using Codex instead of Claude Code
  # Demonstrates using a different AI agent

  dataDir: ~/.agent-orchestrator
  worktreeDir: ~/.worktrees

  defaults:
    agent: codex # Use Codex instead of Claude Code
    runtime: tmux
    workspace: worktree

  projects:
    my-app:
      repo: owner/my-app
      path: ~/my-app
      defaultBranch: main

      # Codex-specific configuration
      agentConfig:
        model: gpt-4
        permissions: default

      agentRules: |
        Write clean, well-documented code.
        Follow project conventions.
        Run tests before pushing.
  ```

  <Info>
    You can switch between different AI agents (claude-code, codex, aider, opencode) by changing the `agent` field.
  </Info>
</Accordion>

## Real-World Use Cases

### Monorepo with Multiple Workspaces

```yaml theme={null}
projects:
  web:
    repo: company/monorepo
    path: ~/monorepo
    defaultBranch: main
    sessionPrefix: web
    postCreate:
      - "pnpm install"
    symlinks: [.env, node_modules]
    agentRules: |
      Work only in packages/web directory.
      Run pnpm build before tests.

  api:
    repo: company/monorepo
    path: ~/monorepo
    defaultBranch: main
    sessionPrefix: api
    postCreate:
      - "pnpm install"
    agentRules: |
      Work only in packages/api directory.
      Update OpenAPI spec for new endpoints.
```

### Team with Different Notification Preferences

```yaml theme={null}
notifiers:
  slack-urgent:
    plugin: slack
    webhook: ${SLACK_WEBHOOK_URL}
    channel: "#urgent-alerts"

  slack-info:
    plugin: slack
    webhook: ${SLACK_WEBHOOK_URL}
    channel: "#agent-logs"

notificationRouting:
  urgent: [desktop, slack-urgent]
  action: [desktop, slack-urgent]
  warning: [slack-info]
  info: [slack-info]
```

### Custom Agent Rules per Language

```yaml theme={null}
projects:
  frontend:
    agentRules: |
      Use TypeScript strict mode.
      Prefer functional components and hooks.
      Add Storybook stories for new components.
      Run Playwright tests before pushing.

  backend:
    agentRules: |
      Write docstrings for all public functions.
      Add type hints (Python 3.10+).
      Use pytest for tests, aim for 80% coverage.
      Format with black, lint with ruff.
```

## Configuration Tips

<Steps>
  <Step title="Start simple">
    Use `simple-github.yaml` as a starting point.
  </Step>

  <Step title="Add complexity incrementally">
    Enable features as you need them.
  </Step>

  <Step title="Test with one project first">
    Get comfortable before adding multiple projects.
  </Step>

  <Step title="Review defaults">
    Most sensible defaults are already configured.
  </Step>

  <Step title="Use environment variables">
    Store API keys in env vars, not config files.
  </Step>
</Steps>

## Environment Variables

Commonly used environment variables:

```bash theme={null}
# Linear integration
export LINEAR_API_KEY="lin_api_..."

# Slack notifications
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."

# GitHub (usually set by gh CLI)
# export GITHUB_TOKEN="ghp_..."
```

<Note>
  Add these to your shell profile (`~/.zshrc` or `~/.bashrc`) to persist them.
</Note>

## Next Steps

After copying an example:

1. **Edit the config** - Update repo paths, team IDs, etc.
2. **Validate** - Run `ao start` to check for config errors
3. **Spawn an agent** - Try `ao spawn project-id ISSUE-123`
4. **Monitor** - Use `ao status` or open the dashboard

See the [Setup Guide](/installation) for detailed configuration reference and troubleshooting.


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