agent-orchestrator-parallel-coding

# Agent Orchestrator — Parallel AI Coding Agents > Skill by [ara.so](https://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)