265 lines
8.1 KiB
Plaintext
265 lines
8.1 KiB
Plaintext
---
|
|
title: Examples
|
|
description: Five annotated starter configurations covering GitHub, Linear, multi-project, auto-merge, and Codex setups.
|
|
---
|
|
|
|
All examples live in the [`examples/` directory](https://github.com/ComposioHQ/agent-orchestrator/tree/main/examples) of the AO repository. Pick the one closest to your setup, copy it to your project root as `agent-orchestrator.yaml`, fill in your repo path and any API keys, and you're ready to spawn agents.
|
|
|
|
```bash
|
|
cp examples/simple-github.yaml agent-orchestrator.yaml
|
|
```
|
|
|
|
---
|
|
|
|
## Simple GitHub
|
|
|
|
For solo devs on a single GitHub repo with GitHub Issues.
|
|
|
|
```yaml title="simple-github.yaml"
|
|
# 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
|
|
```
|
|
|
|
**Notable settings:**
|
|
|
|
- Uses the default GitHub tracker — requires `GITHUB_TOKEN` (set automatically by the `gh` CLI).
|
|
- No `defaults:` block needed — AO's built-in defaults (`tmux` runtime, `claude-code` agent, `worktree` workspace) apply automatically.
|
|
- Replace `owner/my-app` and `~/my-app` with your actual GitHub slug and local checkout path.
|
|
|
|
[View raw file on GitHub](https://github.com/ComposioHQ/agent-orchestrator/blob/main/examples/simple-github.yaml)
|
|
|
|
---
|
|
|
|
## Linear Team
|
|
|
|
For teams that track work in Linear rather than GitHub Issues.
|
|
|
|
```yaml title="linear-team.yaml"
|
|
# 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:).
|
|
```
|
|
|
|
**Notable settings:**
|
|
|
|
- `tracker.plugin: linear` swaps out the default GitHub tracker for the Linear plugin.
|
|
- `tracker.teamId` is your Linear team UUID — find it in Linear → Settings → Team → General.
|
|
- Requires a `LINEAR_API_KEY` environment variable (set it in your shell profile or CI secrets).
|
|
- `agentRules` injects project-specific instructions into every agent's prompt — useful for enforcing commit conventions or test requirements.
|
|
|
|
[View raw file on GitHub](https://github.com/ComposioHQ/agent-orchestrator/blob/main/examples/linear-team.yaml)
|
|
|
|
---
|
|
|
|
## Multi-Project
|
|
|
|
For managing multiple repositories from a single config, with mixed trackers and Slack notifications.
|
|
|
|
```yaml title="multi-project.yaml"
|
|
# 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]
|
|
```
|
|
|
|
**Notable settings:**
|
|
|
|
- `defaults:` sets the runtime, agent, workspace, and notifier list for all projects — individual projects can override any of these.
|
|
- `sessionPrefix` keeps session IDs readable (`fe-123`, `api-456`) when multiple projects run simultaneously.
|
|
- Each project can use a different tracker — `frontend` uses GitHub Issues, `backend` uses Linear.
|
|
- `notifiers.slack.webhook: ${SLACK_WEBHOOK_URL}` reads the webhook URL from an environment variable — never hardcode secrets in config files.
|
|
- `notificationRouting` routes urgent and actionable events to both desktop and Slack, while lower-priority events go to Slack only.
|
|
|
|
[View raw file on GitHub](https://github.com/ComposioHQ/agent-orchestrator/blob/main/examples/multi-project.yaml)
|
|
|
|
---
|
|
|
|
## Auto-Merge
|
|
|
|
For teams that want maximum automation — PRs merge automatically when approved and CI is green, with auto-retry for failures.
|
|
|
|
```yaml title="auto-merge.yaml"
|
|
# 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
|
|
```
|
|
|
|
**Notable settings:**
|
|
|
|
- `reactions.approved-and-green.auto: true` with `action: auto-merge` enables hands-free merging — no human click required once the PR is approved and CI passes.
|
|
- The project-level `reactions` block overrides global reactions for that project only; global `reactions` apply to all projects unless overridden.
|
|
- `ci-failed.retries: 3` lets AO send the agent back to fix CI up to three times before escalating.
|
|
- `changes-requested.escalateAfter: 1h` ensures a human is notified if an agent can't resolve review comments within an hour.
|
|
- `agent-stuck.threshold: 10m` triggers an urgent desktop notification if an agent goes silent for 10 minutes.
|
|
|
|
[View raw file on GitHub](https://github.com/ComposioHQ/agent-orchestrator/blob/main/examples/auto-merge.yaml)
|
|
|
|
---
|
|
|
|
## Codex Integration
|
|
|
|
For teams that prefer GPT-4/Codex over Claude Code.
|
|
|
|
```yaml title="codex-integration.yaml"
|
|
# 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.
|
|
```
|
|
|
|
**Notable settings:**
|
|
|
|
- `defaults.agent: codex` changes the agent for all projects — no need to set it per project.
|
|
- `agentConfig.model: gpt-4` is passed directly to the Codex plugin; valid values depend on your OpenAI subscription and which models the Codex plugin supports.
|
|
- `agentConfig.permissions: default` uses the plugin's built-in permission set — change to `full` to allow broader file access, or `readonly` to restrict writes.
|
|
- Requires an `OPENAI_API_KEY` environment variable.
|
|
|
|
[View raw file on GitHub](https://github.com/ComposioHQ/agent-orchestrator/blob/main/examples/codex-integration.yaml)
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
<Cards>
|
|
<Card title="Configuration Reference" href="/docs/configuration" description="Full reference for every field in agent-orchestrator.yaml." />
|
|
<Card title="Plugins" href="/docs/plugins" description="Browse available runtime, agent, tracker, SCM, notifier, and terminal plugins." />
|
|
<Card title="Guides" href="/docs/guides" description="Step-by-step workflows for common setups and automation patterns." />
|
|
</Cards>
|