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:

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.

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

# 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

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

Linear Integration

Integrate with Linear for issue tracking and team management.

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

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

1. Get your Linear API key

   Visit Linear API Settings and create a new API key.

2. Set environment variable

   echo 'export LINEAR_API_KEY="lin_api_..."' >> ~/.zshrc
   source ~/.zshrc
   
3. Find your team ID

   Your team ID is visible in your Linear workspace URL or via the API.

Multi-Project Setup

Manage multiple repositories with different trackers and notification routing.

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

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

Set SLACK_WEBHOOK_URL environment variable with your Slack incoming webhook URL.

Auto-Merge Configuration

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

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

# 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

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.

Codex Integration

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

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

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

You can switch between different AI agents (claude-code, codex, aider, opencode) by changing the agent field.

Real-World Use Cases

Monorepo with Multiple Workspaces

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

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

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

1. Start simple

   Use simple-github.yaml as a starting point.

2. Add complexity incrementally

   Enable features as you need them.

3. Test with one project first

   Get comfortable before adding multiple projects.

4. Review defaults

   Most sensible defaults are already configured.

5. Use environment variables

   Store API keys in env vars, not config files.

Environment Variables

Commonly used environment variables:

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

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

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 for detailed configuration reference and troubleshooting.