Configuration Examples

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

Get your Linear API key

Visit Linear API Settings and create a new API key.

Set environment variable

echo 'export LINEAR_API_KEY="lin_api_..."' >> ~/.zshrc
source ~/.zshrc

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

Start simple

Use simple-github.yaml as a starting point.

Add complexity incrementally

Enable features as you need them.

Test with one project first

Get comfortable before adding multiple projects.

Review defaults

Most sensible defaults are already configured.

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:

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

See the Setup Guide for detailed configuration reference and troubleshooting.

Additional Resources

Quick Start

Simple GitHub Setup

Linear Integration

Multi-Project Setup

Auto-Merge Configuration

Codex Integration

Real-World Use Cases

Monorepo with Multiple Workspaces

Team with Different Notification Preferences

Custom Agent Rules per Language

Configuration Tips

Environment Variables

Next Steps

Build docs developers (and LLMs) love

Additional Resources

Documentation Index

​Quick Start

​Simple GitHub Setup

​Linear Integration

​Multi-Project Setup

​Auto-Merge Configuration

​Codex Integration

​Real-World Use Cases

​Monorepo with Multiple Workspaces

​Team with Different Notification Preferences

​Custom Agent Rules per Language

​Configuration Tips

​Environment Variables

​Next Steps

Build docs developers (and LLMs) love

Quick Start

Simple GitHub Setup

Linear Integration

Multi-Project Setup

Auto-Merge Configuration

Codex Integration

Real-World Use Cases

Monorepo with Multiple Workspaces

Team with Different Notification Preferences

Custom Agent Rules per Language

Configuration Tips

Environment Variables

Next Steps