Skip to content
/
Tier A A7 PR-lifecycle platform

Agent Orchestrator (ComposioHQ)

agent-orchestrator-composio · last commit 2026-05-24

Primitive shape
No installable primitives
00

Summary

Agent Orchestrator (ComposioHQ) — Summary

Agent Orchestrator (AO) by ComposioHQ is a production-grade TypeScript monorepo platform for spawning and managing parallel AI coding agents, each in its own git worktree with its own branch and PR. The ao CLI (npm: @aoagents/ao) starts a Next.js 15 dashboard at port 3000, then launches an orchestrator agent that spawns per-issue workers. Workers autonomously fix CI failures, address review comments, and open PRs — the engineer only gets pulled in for final merge judgment. The architecture uses 7 plugin slots (Runtime, Agent, Workspace, Tracker, SCM, Notifier, Terminal) supporting multiple providers per slot (tmux/process/Docker runtimes; Claude Code/Codex/Aider agents; GitHub/Linear/GitLab trackers). An openclaw-plugin (Claude Code plugin) provides slash commands and AI tools for controlling AO from within a Claude Code session. AO is the most feature-complete parallel-agents-with-PR-lifecycle framework in the corpus. Compared to seeds: closest to taskmaster-ai (issue-tracker-driven) but AO is a full runtime platform (not a task management plugin), ships a web UI, handles CI-failure reactions and review-comment reactions autonomously, and has a 7-slot plugin architecture rather than a monolithic design.

01

Overview

Agent Orchestrator (ComposioHQ) — Overview

Origin

ComposioHQ. GitHub: https://github.com/ComposioHQ/agent-orchestrator. MIT license. npm: @aoagents/ao. TypeScript. 7,281 stars, very active.

Philosophy

From the README:

"Agent Orchestrator manages fleets of AI coding agents working in parallel on your codebase. Each agent gets its own git worktree, its own branch, and its own PR. When CI fails, the agent fixes it. When reviewers leave comments, the agent addresses them. You only get pulled in when human judgment is needed."

Core model: "agent-agnostic · runtime-agnostic · tracker-agnostic"

How it works (README)

  1. You start — ao start launches dashboard and orchestrator agent
  2. Orchestrator spawns workers — each issue gets its own agent in an isolated git worktree
  3. Agents work autonomously — read code, write tests, create PRs
  4. Reactions handle feedback — CI failures and review comments auto-routed back to agent
  5. You review and merge — pulled in only when human judgment needed

Key design choices

  1. 7-slot plugin architecture — Runtime, Agent, Workspace, Tracker, SCM, Notifier, Terminal are independent plugin slots; lifecycle stays in core
  2. Reaction system — CI failure or review comment triggers send-to-agent action automatically; agents self-repair without human intervention
  3. Git worktree per agent — hard filesystem isolation; each agent's branch is separate from main and from other agents
  4. openclaw-plugin — Claude Code plugin that exposes slash commands and AI tools for controlling AO from within a Claude Code session
  5. macOS wake prevention — holds caffeinate assertion so remote access via Tailscale works while laptop lid is open

"Self-building" origin story

From README article link:

"The Self-Improving AI System That Built Itself" — AO was built using itself, demonstrated in a demo video showing AI agents building the orchestrator.

02

Architecture

Agent Orchestrator (ComposioHQ) — Architecture

Distribution

  • npm package: @aoagents/ao (global install)
  • Install: npm install -g @aoagents/ao
  • Required runtime: Node.js 20.18.3+, Git 2.25+, gh CLI, tmux (macOS/Linux)
  • Nightly: npm install -g @aoagents/ao@nightly

Monorepo structure (pnpm workspace)

packages/
  core/               # Engine: types, config, session manager, lifecycle, plugin registry
  cli/                # CLI tool (ao command) — depends on all plugins
  web/                # Next.js 15 dashboard (App Router, React 19, Tailwind v4)
  ao/                 # Global CLI wrapper (thin shim around cli)
  plugins/
    agent-claude-code/   agent-aider/   agent-codex/   agent-opencode/
    runtime-tmux/        runtime-process/
    workspace-worktree/  workspace-clone/
    tracker-github/      tracker-linear/  tracker-gitlab/
    scm-github/          scm-gitlab/
    notifier-desktop/    notifier-slack/  notifier-webhook/
    notifier-composio/   notifier-openclaw/
    terminal-iterm2/     terminal-web/
  integration-tests/

openclaw-plugin/      # Claude Code plugin (plugin.json, slash commands, AI tools)
skills/               # Bug-triage skill (SKILL.md + scripts/)
artifacts/            # Release artifacts
docs/                 # Documentation

Config file

agent-orchestrator.yaml (auto-generated by ao start):

defaults:
  runtime: tmux       # or process (Windows), docker
  agent: claude-code
  workspace: worktree
  notifiers: [desktop]
projects:
  my-app:
    repo: owner/my-app
    path: ~/my-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
    action: notify

Target AI tools

Claude Code (default), Codex, Aider, OpenCode — via plugin slots.

03

Components

Agent Orchestrator (ComposioHQ) — Components

CLI commands (ao)

Command Purpose
ao start [repo-url] Clone/configure repo, launch dashboard + orchestrator agent
ao stop Gracefully shut down all sessions
ao config-help Print full config schema
ao completion zsh Generate zsh completion file

Plugin slots (7)

Slot Default Alternatives
Runtime tmux (macOS/Linux) / process (Windows) process, docker
Agent claude-code codex, aider, opencode
Workspace worktree clone
Tracker github linear, gitlab
SCM github gitlab
Notifier desktop slack, webhook, composio, openclaw
Terminal iterm2 web

openclaw-plugin (Claude Code plugin)

  • openclaw.plugin.json — plugin manifest
  • Provides slash commands and AI tools for controlling AO from Claude Code
  • Features: health monitoring (poll every 30s), issue board scanning (every 30min), proactive planning, AO CLI control

Skills (1)

skills/bug-triage/SKILL.md — bug triage workflow: gather context → search duplicates → file GitHub issues → push fix PRs. Includes scripts/push_fix_to_github.py (GitHub API-based file editing without local checkout).

Web dashboard

  • Package: packages/web (Next.js 15, React 19, Tailwind v4, xterm.js)
  • Port: 3000
  • Features: session kanban, live terminal streams (xterm.js + WebSocket to tmux PTYs), session detail view, sidebar with all projects

Reaction system

Automated reactions configured in agent-orchestrator.yaml:

  • ci-failed → send-to-agent (agent gets CI logs + fixes)
  • changes-requested → send-to-agent (agent addresses review comments)
  • approved-and-green → notify (human notified to merge)
05

Prompts

Agent Orchestrator (ComposioHQ) — Prompt Excerpts

Excerpt 1: openclaw-plugin description (AI tool usage instructions)

Source: openclaw-plugin/openclaw.plugin.json

{
  "id": "agent-orchestrator",
  "name": "Agent Orchestrator",
  "description": "Control and monitor Agent Orchestrator (AO) from OpenClaw. Slash commands, AI tools, issue board scanning, proactive planning, and health monitoring.",
  "configSchema": {
    "properties": {
      "aoCwd": {
        "description": "Working directory for ao commands. Must contain agent-orchestrator.yaml.",
        "help": "Path to the directory containing agent-orchestrator.yaml. Required — most commands fail without this."
      },
      "healthPollIntervalMs": {
        "description": "How often to poll AO health in milliseconds. Default: 30000 (30s). Set to 0 to disable."
      },
      "boardScanIntervalMs": {
        "description": "How often to scan the issue board for changes. Default: 1800000 (30min). Set to 0 to disable."
      }
    }
  }
}

Prompting technique: Plugin configuration as context — each config field has a description and help string that is surfaced to the AI in tool call context. The aoCwd "Required — most commands fail without this" hint pre-empts a common failure mode.

Excerpt 2: Bug-triage skill

Source: skills/bug-triage/SKILL.md (partial)

## When to use
Any time a bug is reported — in chat, issues, or live observation.

## What it covers
- Full triage workflow: gather context → search duplicates → file/update GitHub issues → push fix PRs
- Root cause analysis with `git log -S` archaeology and upstream dependency research
- GitHub API-based file editing (no local checkout needed) via `scripts/push_fix_to_github.py`
- NPM package regression diffing
- Remote code inspection when the repo isn't cloned locally

## Always pull latest main before triaging. Stale code = bad triage. No exceptions.

Prompting technique: Mandatory precondition ("Always pull latest main... No exceptions") with tooling callout (scripts/push_fix_to_github.py for API-based editing). The skill teaches the AI to work remotely without a local checkout — a non-obvious workflow that requires explicit instruction.

09

Uniqueness

Agent Orchestrator (ComposioHQ) — Uniqueness vs Seeds

Position in taxonomy

AO is the most complete PR lifecycle platform in the corpus. It is not a prompt kit, not a CLI harness, and not a memory layer — it is a production-grade system that takes an issue from tracker to merged PR with minimal human intervention.

Differentiators vs seed frameworks

vs claude-flow / ruflo

Claude-flow/ruflo is a swarm coordination framework with SQLite memory and token budgeting. AO has no swarm, no shared memory, no queen/worker topology — each issue is an isolated independent branch. AO's reaction system (CI+review self-repair) has no equivalent in claude-flow.

vs BMAD-METHOD

BMAD is a document-driven spec workflow for single-agent use. AO replaces the human developer entirely for implementation; BMAD scaffolds the human developer's process.

vs taskmaster-ai

Taskmaster manages a task list within a single session. AO manages parallel per-issue sessions across a git repo, each with its own worktree, CI integration, and PR lifecycle.

vs openspec / kiro

OpenSpec and Kiro produce requirement documents. AO consumes them (via issue tracker) and produces code.

vs claude-conductor

Claude-conductor is a multi-Claude coordination layer. AO uses Claude Code as one swappable plugin slot; its differentiation is the PR lifecycle and tracker integration, not the orchestration topology.

Unique primitives

Primitive Description
Reaction system Declarative YAML rules that auto-route CI failures and review comments to the responsible agent
7-slot plugin architecture Runtime, Agent, Workspace, Tracker, SCM, Notifier, Terminal — each independently swappable
openclaw-plugin First-class Claude Code IDE integration; AO is controllable from within Claude Code
Git worktree isolation Hard per-issue filesystem isolation; no shared workspace between concurrent workers
escalateAfter Time-bounded autonomy — stuck agents escalate to human after configurable timeout
Self-origin AO was partially built by AO itself (dogfooding); this is documented in the project
LastStopState Cross-session restore; ao start recovers the exact set of sessions that were running at last ao stop

What AO is NOT

  • No vector memory / knowledge base
  • No spec-document generation (it consumes specs via issue body)
  • No code review intelligence (it relays human reviewer comments to the agent)
  • No self-improving agent (no RAG over past sessions)

Closest peer in corpus

cli-agent-orchestrator (CAO, AWS Labs) is the closest structural peer: both are background daemons with a dashboard, both use tmux PTY isolation, both support multiple agent CLIs. AO differentiates on: (1) native PR lifecycle + tracker integration, (2) reaction system, (3) plugin architecture, (4) Claude Code IDE plugin. CAO differentiates on: (1) MCP handoff/assign protocol, (2) cron scheduling, (3) event plugins (Discord/Slack/Telegram), (4) AWS provenance.

04

Workflow

Agent Orchestrator (ComposioHQ) — Workflow

Quick start

npm install -g @aoagents/ao
ao start https://github.com/your-org/your-repo
# Dashboard opens at http://localhost:3000

Full lifecycle workflow

ao start
  → Dashboard opens (localhost:3000)
  → Orchestrator agent starts
  → Orchestrator reads issue tracker (GitHub/Linear/GitLab)
  → For each eligible issue:
      → Create git worktree
      → Spawn worker agent (Claude Code/Codex/Aider)
      → Agent reads code, writes tests, creates PR
  → CI runs on PR:
      → CI passed: notify human to review/merge
      → CI failed: send logs to agent → agent fixes
  → PR review:
      → No comments: continue
      → Changes requested: send to agent → agent addresses
      → Approved + green: notify human to merge
  → Human merges (or auto: true for approved-and-green)

Phase artifacts

Phase Artifact
Issue intake Git worktree + branch
Implementation Code changes + tests
PR creation GitHub/GitLab PR
CI feedback Agent-repaired code
Review feedback Updated PR commits
Completion Merged PR

Approval gates

  1. Final merge — human decision always (unless approved-and-green.auto: true)
  2. escalateAfter — if agent is stuck on changes-requested for >30m, escalate to human

TDD

Optional — agents are instructed to write tests but no hard enforcement mechanism is documented.

06

Memory Context

Agent Orchestrator (ComposioHQ) — Memory & Context

State storage

Primary: agent-orchestrator.yaml + per-session runtime state in memory

The lifecycle manager (packages/core/src/lifecycle-manager.ts) maintains session state machine. Session manager (session-manager.ts) handles CRUD + stale runtime reconciliation.

Persistence

project scope — agent-orchestrator.yaml persists project configuration and reaction rules. Session state is in-memory in the running ao start process.

Cross-session handoff

The LastStopState mechanism records which sessions were running before ao stop, enabling restore on next ao start:

  • LastStopState includes otherProjects for cross-project session restore
  • Ctrl+C on ao start performs full graceful shutdown (same as ao stop)

Agent context

Each worker agent gets:

  • Its git worktree (isolated branch)
  • The issue description (from GitHub/Linear/GitLab)
  • CI failure logs (if CI failed, via reaction system)
  • Review comments (if reviewer requested changes)

No persistent vector memory

AO does not ship a knowledge base or vector memory. The git worktree and issue tracker provide sufficient context for each agent session.

openclaw-plugin board scan

The openclaw Claude Code plugin periodically scans the issue board (every 30 min, configurable) and updates its context about open issues. This provides Claude Code users with ambient awareness of the AO project state.

stale runtime reconciliation

The session manager detects dead runtimes (processes that exited without cleanup) and marks sessions as runtime_lost rather than leaving them in an inconsistent state.

07

Orchestration

Agent Orchestrator (ComposioHQ) — Orchestration

Pattern

Parallel fan-out — each eligible issue spawns an independent worker agent session. Sessions run concurrently without cross-session coordination.

Orchestrator agent
  ├── Issue #1 → git worktree → Worker A (Claude Code)
  ├── Issue #2 → git worktree → Worker B (Codex)
  ├── Issue #3 → git worktree → Worker C (Aider)
  └── Issue #N → git worktree → Worker N (...)

Hierarchy

Two-level hierarchy:

  1. Orchestrator agent — reads issue tracker, decides which issues to process, spawns workers
  2. Worker agents — autonomous per-issue; reads code, writes tests, creates PR, handles CI + review feedback

The orchestrator does not supervise worker execution. Workers are fully autonomous once spawned.

Process isolation

Each worker runs in its own:

  • Git worktree — isolated branch, no filesystem collision with other workers
  • tmux session (macOS/Linux) or OS process (Windows)

Plugin slot runtime controls the process model. Default: runtime-tmux.

Execution mode

Background daemon — ao start runs continuously:

  • Orchestrator polls the issue tracker for new/updated issues
  • Reaction system fires on CI/review events (no polling required; webhook-driven)

Multi-model support

The agent plugin slot is swappable at config time:

Agent plugin Target tool
agent-claude-code Claude Code (default)
agent-codex OpenAI Codex CLI
agent-aider Aider
agent-opencode OpenCode

Different projects in the same agent-orchestrator.yaml can use different agent plugins.

Reaction system (event-driven self-repair)

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
    action: notify
  • send-to-agent re-opens the worker session with the failure artifact (CI logs / review comments)
  • retries: 2 limits autonomous CI repair loops
  • escalateAfter: 30m prevents infinite changes-requested loops

Session lifecycle state machine

Managed by packages/core/src/lifecycle-manager.ts:

idle → starting → running → stopping → stopped
                          ↘ runtime_lost  (stale runtime detection)

runtime_lost is set when the session manager detects a dead process that exited without cleanup.

Cross-session restore

LastStopState (persisted at ao stop) records which sessions were running. ao start re-spawns those sessions. otherProjects field enables cross-project restore.

Merge policy

  • Merge is always human-initiated (unless approved-and-green.auto: true)
  • AO never force-pushes or rebases autonomously
08

Ui Cli Surface

Agent Orchestrator (ComposioHQ) — UI & CLI Surface

CLI: ao

Installed globally via npm install -g @aoagents/ao.

Command Description
ao start [repo-url] Clone/configure repo, launch dashboard + orchestrator agent. Opens browser to http://localhost:3000
ao stop Gracefully shut down all sessions (same as Ctrl+C on ao start)
ao config-help Print the full config schema with descriptions
ao completion zsh Generate zsh tab-completion file

Nightly channel: npm install -g @aoagents/ao@nightly

Web dashboard (packages/web)

  • Stack: Next.js 15 (App Router), React 19, Tailwind v4, xterm.js
  • Port: 3000
  • Terminal streams: xterm.js + WebSocket → tmux PTY (live agent output)

Dashboard features

Feature Description
Session kanban Visual board of all sessions by state (idle/running/stopped/runtime_lost)
Live terminal Full xterm.js PTY mirror of each agent's tmux session
Session detail Per-session view: issue context, current state, CI status, review status
Sidebar All projects in the agent-orchestrator.yaml

openclaw-plugin (Claude Code integration)

Directory: openclaw-plugin/ Manifest: openclaw-plugin/openclaw.plugin.json

The plugin provides Claude Code users with AO control without leaving their IDE:

  • Slash commands — AO lifecycle control from Claude Code prompt
  • AI tools — programmatic AO control surfaced as Claude tools
  • Health monitoring — polls AO health every 30s (configurable via healthPollIntervalMs)
  • Board scan — scans issue tracker every 30min (configurable via boardScanIntervalMs), gives Claude ambient awareness of open issues
  • Proactive planning — plugin surfaces issue context so Claude can suggest next actions

Config field aoCwd is required; its description includes "Required — most commands fail without this" to prevent the most common failure mode.

Notifier plugins

Plugin Delivery
notifier-desktop OS desktop notification (default)
notifier-slack Slack message
notifier-webhook HTTP POST
notifier-composio Composio action
notifier-openclaw Surfaces in Claude Code via openclaw-plugin

Terminal plugin

Plugin Description
terminal-iterm2 Opens agent sessions in iTerm2 tabs (macOS)
terminal-web Streams via web dashboard (default for non-macOS)

Related frameworks

same archetype · same primary tool · same memory type

Symphony (OpenAI) ★ 25k
A7 PR-lifecycle platform

A language-agnostic specification and Elixir reference daemon that continuously polls Linear and dispatches isolated Codex…

cli-agent-orchestrator (awslabs) ★ 634
A7 PR-lifecycle platform

tmux-based supervisor-worker orchestration across 7 AI coding CLIs, with MCP coordination primitives, persistent memory,…

Continuous Claude ★ 3.8k
A7 PR-lifecycle platform

Compound learning across Claude Code sessions via PostgreSQL memory extraction from thinking blocks, YAML handoffs for session…

ORCH ★ 68
A7 PR-lifecycle platform

Orchestrates teams of parallel AI agents (CTO + workers + reviewer) on a single codebase with YAML flat-file state, a TUI…

Flokay (Codagent Agent Skills) ★ 26
A7 PR-lifecycle platform

Full SDLC skill pack from idea evaluation through CI-green PR, with TDD Iron Law enforcement and external validator quality gates.