6.8 KiB

Raw Permalink Blame History

Agent Orchestrator

Orchestrate parallel AI coding agents across any runtime, any repo, any issue tracker.

Quick Start

git clone https://github.com/ComposioHQ/agent-orchestrator.git
cd agent-orchestrator && bash scripts/setup.sh
cd ~/your-project && ao init --auto && ao start

That's it! Dashboard opens at http://localhost:3000

What Is This?

Agent Orchestrator spawns and manages multiple AI coding agents working in parallel on your repository. Each agent works in isolation (separate worktrees), handles its own PR lifecycle, and auto-responds to CI failures and review comments.

Key benefits:

🚀 10-30x productivity - Work on 10+ issues simultaneously
🤖 Human-in-the-loop - Agents notify you when judgment needed, not for routine work
🔌 Fully pluggable - Swap any component (runtime, agent, tracker, SCM)
📊 Real-time dashboard - Monitor all agents from one place

Built itself: This project was built using itself (399 commits, 34 PRs, 63 hours of dog-fooding).

Features

Agent-agnostic: Claude Code, Codex, Aider, or bring your own
Runtime-agnostic: tmux, Docker, Kubernetes, or custom
Tracker-agnostic: GitHub Issues, Linear, Jira, or custom
Auto-reactions: CI failures, review comments, merge conflicts → handled automatically
Notifications: Desktop, Slack, Composio, or webhook - only when you're needed
Live terminal: See agents working in real-time through browser

Architecture

8 plugin slots - every abstraction is swappable:

Slot	Interface	Default	Alternatives
Runtime	`Runtime`	tmux	docker, k8s, process
Agent	`Agent`	claude-code	codex, aider, opencode
Workspace	`Workspace`	worktree	clone
Tracker	`Tracker`	github	linear, jira
SCM	`SCM`	github	(gitlab, bitbucket)
Notifier	`Notifier`	desktop	slack, composio, webhook
Terminal	`Terminal`	iterm2	web
Lifecycle	core	—	—

Installation

Prerequisites

Node 20+
Git 2.25+
tmux (for tmux runtime)
gh CLI (for GitHub integration)

Setup

# Clone and run setup
git clone https://github.com/ComposioHQ/agent-orchestrator.git
cd agent-orchestrator
bash scripts/setup.sh

The setup script:

Installs dependencies with pnpm
Builds all packages
Rebuilds node-pty from source (fixes terminal issues)
Links ao CLI globally

Initialize Your Project

cd ~/your-project
ao init --auto  # Auto-detects project type, generates config
ao start        # Launches orchestrator + dashboard

Auto-detection:

Git repo and remote
Project type (languages, frameworks, test runners)
Generates custom agent rules based on your stack

Usage

Spawn Agents

# Spawn agent for a GitHub issue
ao spawn my-project 123

# Spawn for a Linear issue
ao spawn my-project INT-1234

# Spawn without issue (ad-hoc work)
ao spawn my-project

Monitor Progress

# Command-line dashboard
ao status

# Web dashboard
open http://localhost:3000

Manage Sessions

# List all sessions
ao session ls

# Send message to agent
ao send <session-id> "Fix the linting errors"

# Kill session
ao session kill <session-id>

Auto-Reactions

Configure reactions for common scenarios:

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 3

  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 1h

  approved-and-green:
    auto: true
    action: auto-merge

Configuration

Basic config (agent-orchestrator.yaml):

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

defaults:
  runtime: tmux
  agent: claude-code
  workspace: worktree
  notifiers: [desktop]
  agentConfig:
    permissions: skip  # required — see note below

projects:
  my-app:
    repo: owner/my-app
    path: ~/my-app
    defaultBranch: main
    agentRules: |
      Always run tests before pushing.
      Use conventional commits.
      Write clear commit messages.

permissions: skip is required when using claude-code.
Each agent runs in a fresh git worktree it has never seen before. Claude shows
an interactive trust prompt on first entry to any new directory — "Do you trust
the files in this folder?" — and waits for a keypress. Without this flag, every
spawned session silently blocks at that prompt, the dashboard shows all agents
stuck at "spawning", and no work ever gets done. Setting permissions: skip
passes --dangerously-skip-permissions to Claude, bypassing the prompt.
This is safe in the AO context because you are the one creating the worktrees
from your own repository.

See agent-orchestrator.yaml.example for full reference.

Examples

See examples/ directory for:

simple-github.yaml - Minimal GitHub Issues setup
linear-team.yaml - Linear integration
multi-project.yaml - Multiple repos
auto-merge.yaml - Aggressive automation

Development

pnpm install
pnpm build
pnpm dev  # Start web dev server

Project Structure

packages/
  core/          - Core types and services
  cli/           - ao command-line tool
  web/           - Next.js dashboard
  plugins/
    runtime-*/   - Runtime plugins
    agent-*/     - Agent plugins
    workspace-*/ - Workspace plugins
    tracker-*/   - Tracker plugins
    scm-*/       - SCM plugins
    notifier-*/  - Notifier plugins
    terminal-*/  - Terminal plugins

Troubleshooting

See TROUBLESHOOTING.md for common issues and solutions.

Most common:

Terminal not working → node-pty rebuild (automatic via postinstall hook)
Port in use → Kill existing server or change port in config
Config not found → Run ao init from your project directory
All agents stuck at "spawning" forever → agentConfig.permissions: skip is missing from your config. Claude blocks on an interactive trust dialog in each new worktree. Add it under defaults: (see Configuration above).

Philosophy

Push, not pull: Spawn agents, walk away, get notified only when your judgment is needed.

Stateless orchestrator (filesystem > database)
Plugin everything (no vendor lock-in)
Amplify judgment, don't bypass it
Auto-handle routine, escalate complex decisions

Contributing

Contributions welcome! See CLAUDE.md for code conventions and architecture details.

License

MIT

6.8 KiB Raw Permalink Blame History