Skip to content
/
Tier A A7 PR-lifecycle platform

cli-agent-orchestrator (awslabs)

cli-agent-orchestrator · awslabs/cli-agent-orchestrator · ★ 634 · last commit 2026-05-26

tmux-based supervisor-worker orchestration across 7 AI coding CLIs, with MCP coordination primitives, persistent memory, scheduled flows, and a bundled React dashboard — without replacing any existing CLI tool.

Best whenOrchestration should preserve each tool's native features by running real CLI processes in tmux PTYs, not by wrapping APIs.
Skip ifReplacing CLI tools with API wrappers, Mixing supervisor context with worker context
vs seeds
claude-flow(MCP coordination backbone) but CAO's MCP is a thin routing layer (handoff/assign/send_message) rather than a 305-tool l…
Primitive shape 11 total
Skills 3 Subagents 3 MCP tools 5
00

Summary

CLI Agent Orchestrator (CAO) — Summary

CLI Agent Orchestrator (CAO) by AWS Labs is an open-source Python framework that orchestrates multiple existing AI coding CLI tools (Claude Code, Kiro CLI, Codex CLI, Gemini CLI, Kimi CLI, GitHub Copilot CLI, OpenCode, Amazon Q Developer) by running each in an isolated tmux session and coordinating them via MCP primitives. CAO does not replace any CLI — it wraps them. The coordination model is supervisor-worker: a supervisor agent (running in one CLI) delegates to worker agents (running in other CLIs) via three MCP tools: handoff (sync, wait), assign (async, fire-and-forget), send_message (inbox delivery). Workers run as real CLI processes with full PTY access, preserving each tool's native features (Claude Code sub-agents, Q Developer custom agents). CAO ships a bundled React web dashboard at port 9889, a standalone cao CLI, an MCP management server (cao-ops-mcp), persistent memory across sessions, cron-style flow scheduling, and an event plugin system (Discord/Slack/Telegram/webhook). Compared to seeds: most similar to claude-conductor (markdown scaffold for cross-session coordination) but CAO is a full runtime infrastructure layer rather than a markdown methodology, ships a web UI, uses tmux for real process isolation, and is agent-agnostic across 7 CLI tools.

01

Overview

CLI Agent Orchestrator (CAO) — Overview

Origin

AWS Labs. GitHub: https://github.com/awslabs/cli-agent-orchestrator. Apache-2.0 license. PyPI package: cli-agent-orchestrator. Python-based. 634 stars, active (last commit 2026-05-26).

Philosophy

From the README:

"CAO (pronounced 'kay-oh') is a lightweight local orchestrator that sits between you and the CLI coding agents you already use. Instead of running a single agent at a time, CAO lets a supervisor agent launch, message, and coordinate multiple worker agents — each one a real CLI tool (Claude Code, Kiro, Codex, etc.) running in its own tmux terminal."

Key principle: full CLI preservation:

"Because every agent is a full CLI process, CAO preserves tool behaviour, auth, and advanced features (Claude Code sub-agents, Q CLI custom agents, etc.) that a raw API wrapper cannot."

Design choices

  1. tmux-based isolation — each agent is a real PTY process in its own tmux session. Humans can tmux attach -t <session> to watch or steer any agent in real time.
  2. MCP as coordination protocol — the three coordination primitives (handoff, assign, send_message) are MCP tools that any AI agent can call, making the orchestration protocol accessible to the AI itself.
  3. Agent-agnostic — 7 supported providers; mixing providers (Kiro supervisor → Claude Code worker) is a first-class use case.
  4. Cross-provider tool restrictions — role + allowedTools in agent profiles; 5 of 7 providers support hard enforcement.
  5. cao-ops-mcp — a secondary MCP server that lets the supervisor agent spawn and manage CAO sessions from within its own chat loop (meta-orchestration).
  6. Scheduled flows — cron-style scheduling for unattended agent runs.

AWS motivation

The project targets enterprise/cloud teams using Amazon Q Developer alongside other tools, enabling Q Developer to be orchestrated alongside Claude Code or Codex in the same workflow.

02

Architecture

CLI Agent Orchestrator (CAO) — Architecture

Distribution

  • PyPI package: cli-agent-orchestrator
  • Install: uv tool install git+https://github.com/awslabs/cli-agent-orchestrator.git@main (or uv tool install cli-agent-orchestrator from PyPI)
  • Required runtime: Python 3.10+, tmux 3.3+, uv
  • No Node.js required — pre-built React UI bundled in the wheel

CLI binaries

  • cao — primary CLI
  • cao-server — starts MCP server at localhost:9889

Directory structure (key paths)

src/cli_agent_orchestrator/
  cli/
    commands/         # launch, init, install, shutdown, flow, session, memory, skills, etc.
    main.py           # cao CLI entry point
  mcp_server/         # Primary MCP server (handoff, assign, send_message, memory tools)
  ops_mcp_server/     # cao-ops-mcp (lets AI spawn/manage CAO sessions)
  agent_store/        # Agent profiles storage
  providers/          # 7 CLI provider adapters
  services/           # Session management, scheduling, memory
  plugins/            # Event plugin system

skills/
  cao-session-management/  SKILL.md
  cao-provider/            SKILL.md
  cao-supervisor-protocols/ SKILL.md

web/                        # Pre-built React dashboard (bundled in wheel)

Config

Agent profiles are Markdown files with YAML front matter:

---
name: code_supervisor
provider: kiro_cli
allowedTools: [read, write, bash]
---
# Supervisor Agent
(system prompt)
  • ~/.aws/cli-agent-orchestrator/agent-store/ — local agent profile store
  • ~/.aws/cli-agent-orchestrator/agent-context/ — built-in agent definitions

Target AI tools (7)

Kiro CLI (default), Claude Code, Codex CLI, Gemini CLI, Kimi CLI, GitHub Copilot CLI, OpenCode, Amazon Q Developer CLI.

03

Components

CLI Agent Orchestrator (CAO) — Components

CLI commands (11)

Command Purpose
cao launch Start a supervisor + optional workers in tmux sessions
cao init Initialize CAO in a directory
cao install <profile> Install an agent profile
cao shutdown Terminate sessions
cao flow Manage scheduled flows (cron-style)
cao session List/status/manage sessions
cao memory Store/recall/list cross-session memories
cao skills List/manage installed skills
cao terminal Attach/detach from agent terminals
cao mcp-server Start/stop the MCP server
cao env Manage environment variables

MCP servers (2)

Primary MCP server (cao-server, port 9889)

Orchestration primitives (3):

  • handoff — transfer control to another agent, wait for completion (sync)
  • assign — fire-and-forget task to another agent (async)
  • send_message — deliver message to agent's inbox

Memory tools (2):

  • memory_store — persist knowledge across sessions
  • memory_recall — retrieve relevant memories (injected at session start automatically)

cao-ops-mcp (meta-orchestration)

Allows a supervisor AI agent to spawn and manage CAO sessions from its own chat loop. Enables fully AI-driven multi-agent orchestration without human involvement.

Skills (3)

  • cao-session-management — how to launch/monitor/shutdown CAO sessions
  • cao-provider — provider-specific setup and best practices
  • cao-supervisor-protocols — supervisor agent behavioral guidelines

Agent profiles (built-in examples)

  • code_supervisor — supervisor agent
  • developer — worker: general development
  • reviewer — worker: code review

Event plugins

  • Discord, Slack, Telegram, webhook — forward inter-agent messages to external channels

Web dashboard (React, port 9889)

Pre-built React bundle, no Node.js needed. Features: session management, agent terminals, flows.

05

Prompts

CLI Agent Orchestrator (CAO) — Prompt Excerpts

Excerpt 1: CAO Session Management skill

Source: skills/cao-session-management/SKILL.md

## Core Concepts

- **Session**: A group of agent terminals working together
- **Conductor**: The supervisor terminal — receives instructions, delegates to workers
- **Provider**: LLM backend. Default `kiro_cli`, override with `--provider`

## Prerequisites

Before launching a session, verify:

- **`cao-server` is running** at `localhost:9889`. Quick check:
  ```bash
  curl -sf http://localhost:9889/sessions >/dev/null && echo OK || echo "start cao-server"

If not running, start it in a separate terminal: cao-server.

  • The agent profile is installed. cao launch --agents <profile> fails if the profile is unknown. Install built-ins or custom files with cao install <profile|path|url>.

Quick Example

A complete, copy-pasteable supervisor launch. The default provider is kiro_cli; pass --provider <name> to use another (claude_code, codex, gemini_cli, kimi_cli, copilot_cli, opencode_cli, q_cli).

cao install code_supervisor
cao install developer
cao install reviewer

cao launch --agents code_supervisor --headless --yolo \
  --session-name my-task --working-directory '/path/to/project' \
  "Build a hello-world Python script. Delegate to developer, then reviewer."


**Prompting technique**: Prerequisite gate with verification command. The skill instructs the AI
to check server health (`curl -sf`) before attempting launch — a defensive pattern preventing
silent failures.

---

## Excerpt 2: Skill describes MCP tool usage for orchestration

```markdown
## Discovering Available Profiles

| Source | Command |
|--------|---------|
| All available profiles | `curl -sf http://localhost:9889/agents/profiles` — canonical, provider-agnostic |
| Custom/local files | `ls ~/.aws/cli-agent-orchestrator/agent-store/` |
| Built-in profiles | see README Quick Start |

The HTTP endpoint is the recommended check: it scans the built-in packaged store, the local
store (`agent-store/`), and provider-specific directories, then returns a deduplicated list (by
profile name, built-in wins) with a `source` label on each entry.

If unsure which profile to use, ask the user rather than guessing.

Prompting technique: API-over-file-listing guidance — the skill directs the AI to query an HTTP endpoint rather than use shell commands for profile discovery, enforcing use of the authoritative data source.

09

Uniqueness

CLI Agent Orchestrator (CAO) — Uniqueness & Positioning

Differs from seeds

No direct match among the 11 seeds. CAO occupies a unique "meta-orchestration infrastructure" niche — it orchestrates other frameworks rather than implementing a methodology.

Closest seed analogy: claude-flow in having a dedicated MCP server as the coordination backbone. But CAO's MCP is a thin routing layer (handoff/assign/send_message) rather than a tool library. Claude-flow owns the agent runtime; CAO delegates to existing CLI tools.

Key differentiators from all 11 seeds:

  1. CLI-tool-agnostic — works with 7 AI coding CLIs simultaneously. All seeds target a single tool (Claude Code, Roo Code, Kiro). CAO is the only framework designed to coordinate heterogeneous CLI tools in the same workflow.

  2. tmux PTY isolation — real process isolation with PTY access. All seeds modify a single AI session; CAO creates separate OS processes per agent. Humans can attach to any session.

  3. cao-ops-mcp meta-layer — the primary AI agent can itself spawn and manage CAO sessions, creating a recursive orchestration capability not present in any seed.

  4. AWS provenance + Amazon Q — the only framework in the batch with an enterprise cloud vendor pedigree, explicitly supporting Amazon Q Developer alongside other tools.

  5. Bundled React dashboard in a Python wheel — shipping a pre-built frontend inside the Python package (no Node.js install required) is an unusual DX choice not matched by any seed.

  6. Scheduled flows + event plugins — cron-style scheduling and Discord/Slack/Telegram event forwarding make CAO suitable for always-on team infrastructure.

Observable failure modes

  • tmux 3.3+ requirement is a non-trivial installation step on some systems
  • Session state lost on cao-server restart
  • Windows support only via CAO_ENABLE_WORKING_DIRECTORY workaround (not native)
  • No persistent audit log of agent decisions
  • The framework is infrastructure, not methodology — it requires well-crafted agent profiles

Competitive positioning

CAO is the only framework in the corpus positioned as infrastructure for teams already using multiple AI coding tools. It does not prescribe how to code; it manages which agent does what and ensures they can communicate across tool boundaries.

04

Workflow

CLI Agent Orchestrator (CAO) — Workflow

Quick start workflow

cao-server                              # Start MCP server

cao install code_supervisor             # Install profiles
cao install developer
cao install reviewer

cao launch --agents code_supervisor \   # Start supervisor session
  --provider claude_code \
  --session-name my-task \
  "Build a hello-world Python script. Delegate to developer, then reviewer."

cao session status cao-my-task          # Monitor progress
cao shutdown --session cao-my-task      # Clean up

Multi-agent delegation workflow

1. Supervisor receives task via user message or cao launch
2. Supervisor analyzes → uses handoff/assign MCP tools to spawn workers
3. Workers execute in isolated tmux sessions
4. Workers report back via send_message → supervisor's inbox
5. Supervisor synthesizes → responds to user or completes task

Orchestration modes

Mode Behavior
handoff Supervisor transfers control, blocks until worker completion
assign Supervisor fires task, continues other work, collects result later
send_message One-way message to another agent's inbox

Scheduled flows

cao flow — cron-style scheduling:

# example flow
schedule: "0 9 * * 1-5"   # weekdays 9am
task: "Review overnight CI results and create summary"
provider: claude_code

Phase artifacts

Phase Artifact
Session start tmux session with agent PTY
Execution code changes in working directory
Memory storage memory_store entries in MCP server
Completion session status COMPLETED

Approval gates

Human-in-the-loop via tmux: any human can tmux attach -t <session> to watch or steer. No automated approval gates — the framework is designed for supervised but not blocked workflows.

06

Memory Context

CLI Agent Orchestrator (CAO) — Memory & Context

Persistent memory

memory_store and memory_recall MCP tools provide cross-session persistent memory.

  • Memories are stored by the MCP server (backed by ~/.aws/cli-agent-orchestrator/ storage)
  • At session start, CAO automatically injects relevant memories as context into the new session
  • Agents can store and recall knowledge without explicit programmer effort

Memory injection

From README:

"Agents store and recall knowledge across sessions using memory_store and memory_recall MCP tools. CAO automatically injects relevant memories as context at session start."

State storage

Session state (IDLE / PROCESSING / COMPLETED / ERROR) is tracked by the MCP server process. Each agent terminal is assigned a unique CAO_TERMINAL_ID environment variable for routing.

Persistence scope

global — memories persist across sessions and projects.

Agent context at session start

On session launch, CAO:

  1. Injects the agent profile's system prompt
  2. Injects any relevant stored memories
  3. Sets CAO_TERMINAL_ID for MCP routing

Cross-agent message passing

send_message MCP tool — delivers messages to named agent inboxes. Inbox messages are available to the receiving agent on its next turn.

No compaction

Context compaction is not managed by CAO; each CLI tool handles its own context within the PTY session. Long-running sessions hit CLI-native context limits.

07

Orchestration

CLI Agent Orchestrator (CAO) — Orchestration

Pattern

Hierarchical with optional parallel fan-out — one supervisor delegates to N workers via handoff (blocking) or assign (non-blocking). Workers report back via send_message.

Isolation mechanism

tmux-pane — each agent runs in an isolated tmux session with a real PTY. Session names are prefixed with cao-. Humans can attach with tmux attach -t cao-<name>.

Multi-model

Yes — cross-provider mixing is a first-class feature. The supervisor can run on Kiro CLI while workers run on Claude Code, Codex, or Gemini CLI. Per-provider configuration:

# Agent profile frontmatter
provider: claude_code    # or kiro_cli, codex, gemini_cli, kimi_cli, copilot_cli, q_cli

Subagent definition format

persona-md — agent profiles are Markdown files with YAML front matter specifying name, provider, allowedTools, role. Body is the system prompt.

Execution mode

interactive-loop (default) or background-daemon (via --headless --async). Flows use scheduled mode for cron-based unattended execution.

Spawn mechanism

cao launch --agents <profile> from CLI, or cao-ops-mcp tools from within an AI agent session.

Max concurrent agents

Configurable — no documented hard limit. Bounded by system tmux session capacity.

Crash recovery

Not documented. Session state is in-memory in the MCP server. Restarting cao-server loses active session tracking. The tmux sessions themselves persist until explicitly killed.

HITL (human in the loop)

A human can tmux attach -t <session> to any running agent session at any time to watch, type, or steer the agent. This is a first-class feature explicitly called out in the README.

08

Ui Cli Surface

CLI Agent Orchestrator (CAO) — UI & CLI Surface

CLI binary

Binary name: cao Entry: Python Click application

Subcommands: launch, init, install, shutdown, flow, session, memory, skills, terminal, mcp-server, env

Second binary: cao-server — starts the MCP + web server at localhost:9889.

Web dashboard

Exists: yes Type: web-dashboard Port: 9889 Tech stack: React (pre-built, bundled in Python wheel — no Node.js required to use) Features: session management, agent terminals, flow scheduling

From README:

"CAO ships a bundled web dashboard for managing agents, terminals, and flows from the browser. The pre-built UI is packaged inside the wheel, so there is nothing extra to install — just start the server: cao-server. Then open http://localhost:9889."

Dashboard screenshot shows: session list, live terminal streams, status indicators.

cao-ops-mcp (meta-orchestration MCP server)

A second MCP server exposing tools that allow a primary AI agent to spawn and monitor CAO sessions from within its own agentic loop. This enables AI-driven orchestration without human CLI involvement.

tmux integration

All agent sessions run in named tmux sessions. From README:

tmux attach -t cao-<session-name>   # Watch agent in real time
cao terminal                        # Interactive window selector

Event plugins (observability)

Forward inter-agent messages to Discord, Slack, Telegram, or any webhook target. This enables external visibility into agent communication without watching the tmux sessions.

Zsh completion

cao completion zsh > ~/.zsh/completions/_cao — shell completion for all commands.

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…

Agent Orchestrator (ComposioHQ)
A7 PR-lifecycle platform
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.

Anthropic Knowledge Work Plugins ★ 16k
A4 Markdown scaffold

Role-specialized plugin bundles with live MCP connectors that turn Claude into a domain expert for enterprise knowledge workers.