Agent Orchestrator — Parallel AI Coding Agents

Skill by ara.so — AI Agent Skills collection.

Agent Orchestrator is an agentic orchestration layer that spawns parallel AI coding agents, each in its own git worktree. Agents autonomously fix CI failures, address review comments, and open PRs while you supervise from a unified dashboard.

Core Concepts

Orchestrator Agent: Plans tasks, spawns worker agents, monitors progress
Worker Agents: Isolated agents working on individual issues/features
Git Worktrees: Each agent gets its own filesystem workspace
Reactions: Automated responses to CI failures, review comments, approvals
Plugin Architecture: Extensible runtime, agent, workspace, tracker, SCM, notifier, terminal plugins

Installation

Global CLI Installation

bash

npm install -g @aoagents/ao

For nightly builds from main:

bash

npm install -g @aoagents/ao@nightly

From Source (Contributors)

bash

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

Prerequisites

Node.js 20+
Git 2.25+ (worktree support)
```
gh
```
CLI (authenticated)
macOS/Linux: tmux (
```
brew install tmux
```
or
```
sudo apt install tmux
```
)
Windows: PowerShell 7+ (uses native ConPTY, no tmux needed)

Quick Start

Start from GitHub URL

bash

ao start https://github.com/your-org/your-repo

Start from Local Repo

bash

cd ~/your-project
ao start

Start Multiple Projects

bash

ao start ~/path/to/project-one
ao start https://github.com/org/project-two

The dashboard opens at

http://localhost:3000

by default.

Configuration

On first run,

ao start

generates

agent-orchestrator.yaml

yaml

$schema: https://raw.githubusercontent.com/ComposioHQ/agent-orchestrator/main/schema/config.schema.json
port: 3000

defaults:
  runtime: tmux       # tmux on macOS/Linux, process on Windows
  agent: claude-code  # or codex, aider, cursor, opencode, kimicode
  workspace: worktree # or clone
  notifiers: [desktop]

projects:
  my-app:
    repo: owner/my-app
    path: ~/my-app
    defaultBranch: main
    sessionPrefix: app
    
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 2
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 30m
  approved-and-green:
    auto: false  # Set to true for auto-merge
    action: notify

power:
  preventIdleSleep: true  # Keeps Mac awake for remote access

Multi-Project Configuration

yaml

projects:
  frontend:
    repo: org/frontend
    path: ~/work/frontend
    defaultBranch: main
    sessionPrefix: fe
    
  backend:
    repo: org/backend
    path: ~/work/backend
    defaultBranch: develop
    sessionPrefix: be
    
  docs:
    repo: org/documentation
    path: ~/work/docs
    defaultBranch: main
    sessionPrefix: docs

CLI Commands

Session Management

bash

# List all active sessions
ao list

# Start a new agent session
ao new "Fix login validation bug" --project my-app --issue 123

# Attach to existing session
ao attach my-app-fix-login

# Stop a session
ao stop my-app-fix-login

# Stop all sessions for a project
ao stop --project my-app --all

Project Management

bash

# Add project
ao add-project ~/path/to/repo

# Remove project
ao remove-project my-app

# Show configuration
ao config-help

Status & Monitoring

bash

# Show all sessions and their status
ao status

# Show detailed session info
ao status my-app-fix-login

# View logs
ao logs my-app-fix-login

Zsh Completion

bash

# Generate completion file
mkdir -p ~/.zsh/completions
ao completion zsh > ~/.zsh/completions/_ao

# Add to ~/.zshrc before compinit
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit
compinit

Plugin Configuration

Runtime Plugins

yaml

defaults:
  runtime: tmux  # or process, docker

tmux (default on macOS/Linux):

Persistent sessions
Attach from multiple terminals
Scrollback history

process (default on Windows):

Native ConPTY support
No tmux dependency
Set
```
AO_SHELL=bash
```
for Git Bash

docker:

Complete isolation
Reproducible environments

Agent Plugins

yaml

defaults:
  agent: claude-code  # or codex, aider, cursor, opencode, kimicode

Each agent plugin implements the

AgentPlugin

interface:

typescript

export interface AgentPlugin {
  name: string;
  start(config: AgentConfig): Promise<void>;
  stop(sessionId: string): Promise<void>;
  sendMessage(sessionId: string, message: string): Promise<void>;
  getStatus(sessionId: string): Promise<AgentStatus>;
}

Workspace Plugins

yaml

defaults:
  workspace: worktree  # or clone

worktree: Single repo, multiple working directories (recommended) clone: Full repository clone per session

Tracker Plugins

yaml

defaults:
  tracker: github  # or linear, gitlab

Integration with issue tracking systems to fetch context and update status.

Notifier Plugins

yaml

defaults:
  notifiers: [desktop, slack]  # Available: desktop, slack, discord, composio, webhook, openclaw

Multiple notifiers can be active simultaneously.

Reaction Patterns

Auto-Fix CI Failures

yaml

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 2
    message: "CI failed with the following errors: {{errors}}"

When CI fails, the orchestrator sends logs to the agent automatically. After 2 retries, escalation occurs.

Auto-Address Review Comments

yaml

reactions:
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 30m
    message: "Reviewer requested: {{comments}}"

The agent gets review comments and attempts to address them. If not resolved in 30 minutes, you're notified.

Auto-Merge on Approval

yaml

reactions:
  approved-and-green:
    auto: true  # Enable auto-merge
    action: merge
    strategy: squash  # or merge, rebase
    deleteAfter: true

When PR is approved and CI passes, automatically merge and delete the branch.

Custom Reactions

yaml

reactions:
  label-added:
    auto: true
    condition: "label == 'needs-tests'"
    action: send-to-agent
    message: "Please add tests for this change"

Working with Sessions

Creating a Session Programmatically

typescript

import { SessionManager } from '@aoagents/core';

const manager = new SessionManager();

const session = await manager.create({
  projectId: 'my-app',
  name: 'fix-auth-bug',
  issue: 'GH-456',
  branch: 'fix/auth-validation',
  agent: 'claude-code',
  runtime: 'tmux',
  workspace: 'worktree'
});

// Session is now running in isolated worktree
console.log(`Session ${session.id} started at ${session.workspacePath}`);

Sending Messages to Agent

bash

# Via CLI
ao send my-app-fix-auth "Review the authentication flow in src/auth.ts"

# Via API
ao api POST /sessions/my-app-fix-auth/message -d '{"content":"Check the auth flow"}'

Monitoring Session Status

typescript

import { SessionManager } from '@aoagents/core';

const manager = new SessionManager();
const status = await manager.getStatus('my-app-fix-auth');

console.log(`Agent: ${status.agent}`);
console.log(`State: ${status.state}`);  // idle, working, waiting, error
console.log(`Current task: ${status.currentTask}`);
console.log(`Branch: ${status.branch}`);
console.log(`Workspace: ${status.workspacePath}`);

Git Worktree Management

Agent Orchestrator uses git worktrees to isolate agents:

bash

# Worktrees are automatically created under:
~/my-app/.worktrees/fix-auth-bug/

# Each worktree has its own:
# - Working directory
# - HEAD pointer
# - Index
# - Branch

Worktree Cleanup

bash

# Cleanup happens automatically on session stop
ao stop my-app-fix-auth

# Manual cleanup if needed
cd ~/my-app
git worktree remove .worktrees/fix-auth-bug
git branch -D fix/auth-validation

Dashboard API

The orchestrator exposes a REST API (default port 3000):

List Sessions

bash

curl http://localhost:3000/api/sessions

Create Session

bash

curl -X POST http://localhost:3000/api/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "my-app",
    "issue": "GH-789",
    "title": "Add user export feature"
  }'

Get Session Status

bash

curl http://localhost:3000/api/sessions/my-app-export/status

Send Message

bash

curl -X POST http://localhost:3000/api/sessions/my-app-export/message \
  -H "Content-Type: application/json" \
  -d '{"content": "Export to CSV format"}'

Stop Session

bash

curl -X DELETE http://localhost:3000/api/sessions/my-app-export

Building Plugins

Agent Plugin Example

typescript

// plugins/agent-custom/src/index.ts
import { AgentPlugin, AgentConfig, AgentStatus } from '@aoagents/core';

export class CustomAgentPlugin implements AgentPlugin {
  name = 'custom-agent';
  
  async start(config: AgentConfig): Promise<void> {
    // Initialize agent in workspace
    const { workspacePath, sessionId, task } = config;
    
    // Launch agent process
    // Set up communication channel
    // Return when ready
  }
  
  async stop(sessionId: string): Promise<void> {
    // Cleanup agent process
    // Save state if needed
  }
  
  async sendMessage(sessionId: string, message: string): Promise<void> {
    // Forward message to agent
  }
  
  async getStatus(sessionId: string): Promise<AgentStatus> {
    return {
      state: 'working',
      currentTask: 'Analyzing codebase',
      lastActivity: new Date()
    };
  }
}

export default {
  agent: new CustomAgentPlugin()
};

Notifier Plugin Example

typescript

// plugins/notifier-telegram/src/index.ts
import { NotifierPlugin, Notification } from '@aoagents/core';

export class TelegramNotifierPlugin implements NotifierPlugin {
  name = 'telegram';
  
  constructor(private botToken: string, private chatId: string) {}
  
  async notify(notification: Notification): Promise<void> {
    const { title, message, level, sessionId } = notification;
    
    const text = `*${title}*\n${message}\nSession: ${sessionId}`;
    
    await fetch(`https://api.telegram.org/bot${this.botToken}/sendMessage`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        chat_id: this.chatId,
        text,
        parse_mode: 'Markdown'
      })
    });
  }
}

export default {
  notifier: new TelegramNotifierPlugin(
    process.env.TELEGRAM_BOT_TOKEN!,
    process.env.TELEGRAM_CHAT_ID!
  )
};

Environment Variables

bash

# Agent credentials
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

# GitHub integration
export GITHUB_TOKEN=ghp_...

# Notifier credentials
export SLACK_WEBHOOK_URL=https://hooks.slack.com/...
export DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# Windows shell preference
export AO_SHELL=bash  # Use Git Bash instead of PowerShell

# Custom config location
export AO_CONFIG=~/custom/agent-orchestrator.yaml

Troubleshooting

Worktree Already Exists

bash

# Error: worktree already exists
# Solution: Clean up manually
git worktree remove .worktrees/session-name --force
git branch -D branch-name

tmux Not Found (macOS/Linux)

bash

# Install tmux
brew install tmux       # macOS
sudo apt install tmux   # Ubuntu/Debian

# Or switch to process runtime
ao config set defaults.runtime process

Agent Not Responding

bash

# Check session logs
ao logs session-name

# Check agent process
ao status session-name

# Restart session
ao stop session-name
ao new "Same task" --project my-app --issue 123

Port Already in Use

yaml

# agent-orchestrator.yaml
port: 3001  # Change from default 3000

GitHub Auth Issues

bash

# Re-authenticate gh CLI
gh auth login

# Verify token has required scopes
gh auth status

Merge Conflicts in Worktree

bash

# Agent handles automatically via reaction
# Or attach and resolve manually
ao attach session-name
# Inside session: resolve conflicts, commit, push

Best Practices

One issue per session: Each agent works on a single, well-defined task
Use worktrees: Better isolation and performance than clones
Configure reactions: Automate CI fixes and review responses
Monitor dashboard: Track progress across all agents
Escalate complex decisions: Let agents handle routine, you handle judgment calls
Clean up regularly: Remove merged branches and completed worktrees
Test reactions: Start with
```
auto: false
```
, validate behavior, then enable
Use session prefixes: Organize sessions by project for clarity

Remote Access

yaml

# Keep Mac awake for remote dashboard access
power:
  preventIdleSleep: true  # Default on macOS

Access dashboard remotely via Tailscale or VPN:

```
http://your-mac-tailscale-ip:3000
```

Note: Lid-close sleep cannot be prevented on macOS. Use clamshell mode (external display + power) for lid-closed access.

Development & Testing

bash

# Clone and build
git clone https://github.com/ComposioHQ/agent-orchestrator.git
cd agent-orchestrator
pnpm install
pnpm build

# Run tests (3,288 test cases)
pnpm test

# Start dev server
pnpm dev

# Build plugins
cd packages/plugin-agent-custom
pnpm build

Advanced: Custom Orchestrator Agent

Create a custom orchestrator that uses different planning logic:

typescript

// orchestrator-custom.ts
import { OrchestratorAgent, Task, SessionManager } from '@aoagents/core';

class CustomOrchestrator extends OrchestratorAgent {
  async plan(goal: string): Promise<Task[]> {
    // Custom planning logic
    const tasks = await this.breakdownGoal(goal);
    
    return tasks.map(task => ({
      id: this.generateId(),
      title: task.title,
      description: task.description,
      dependencies: task.deps,
      estimatedEffort: task.effort
    }));
  }
  
  async spawn(task: Task): Promise<string> {
    const manager = new SessionManager();
    
    const session = await manager.create({
      projectId: this.projectId,
      name: this.toSessionName(task.title),
      issue: task.id,
      branch: this.toBranchName(task.title),
      agent: this.selectAgent(task),
      runtime: 'tmux',
      workspace: 'worktree'
    });
    
    return session.id;
  }
}

This skill covers the complete usage of Agent Orchestrator for spawning and managing parallel AI coding agents with autonomous reactions, git worktree isolation, and extensible plugin architecture.

agent-orchestrator-parallel-coding

NPX Install

Tags

SKILL.md Content

Agent Orchestrator — Parallel AI Coding Agents

Core Concepts

Installation

Global CLI Installation

From Source (Contributors)

Prerequisites

Quick Start

Start from GitHub URL

Start from Local Repo

Start Multiple Projects

Configuration

Multi-Project Configuration

CLI Commands

Session Management

Project Management

Status & Monitoring

Zsh Completion

Plugin Configuration

Runtime Plugins

Agent Plugins

Workspace Plugins

Tracker Plugins

Notifier Plugins

Reaction Patterns

Auto-Fix CI Failures

Auto-Address Review Comments

Auto-Merge on Approval

Custom Reactions

Working with Sessions

Creating a Session Programmatically

Sending Messages to Agent

Monitoring Session Status

Git Worktree Management

Worktree Cleanup

Dashboard API

List Sessions

Create Session

Get Session Status

Send Message

Stop Session

Building Plugins

Agent Plugin Example

Notifier Plugin Example

Environment Variables

Troubleshooting

Worktree Already Exists

tmux Not Found (macOS/Linux)

Agent Not Responding

Port Already in Use

GitHub Auth Issues

Merge Conflicts in Worktree

Best Practices

Remote Access

Development & Testing

Advanced: Custom Orchestrator Agent