CLI Agent Orchestrator (CAO)

CLI Agent Orchestrator (CAO) coordinates multiple AI coding CLIs so a
supervisor can delegate work to specialist agents in parallel or sequence.

What CAO does

CAO runs a local cao-server, starts provider CLIs in isolated terminal
sessions, and gives a supervisor tools for coordinating workers. The agents
remain full CLI processes with their native authentication and capabilities.
See CODEBASE.md for the runtime architecture and package layout.

Prerequisites

Install:

Python 3.10 or later
tmux 3.3 or later
uv
At least one supported provider CLI, authenticated before you launch CAO:
Kiro CLI, Claude Code,
Codex CLI, Antigravity CLI,
Hermes, Kimi CLI,
GitHub Copilot CLI,
OpenCode CLI, or
Cursor CLI

The focused provider guides contain installation, authentication, and
provider-specific behavior.

Install CAO

Install the current main branch as a uv tool:

uv tool install git+https://github.com/awslabs/cli-agent-orchestrator.git@main --upgrade
cao --help

For a tagged release, install
cli-agent-orchestrator from PyPI.
See DEVELOPMENT.md for a source checkout.
For container-based installation, see the
devcontainer feature.

To update an existing CAO installation:

cao update

See Updating CAO for source-aware behavior and edge cases.

First supervisor launch

The unqualified commands below use CAO's default Kiro CLI provider. If you
installed a different provider, follow its focused guide above for the
provider override while keeping the same sequence.

Install the built-in supervisor profile:
```
cao install code_supervisor
```
In terminal A, start the local server and leave it running:
```
cao-server
```
In terminal B, change to the project directory the agents should work in,
then launch the supervisor:
```
cd /path/to/your/project
cao launch --agents code_supervisor
```
Observe the supervisor in the attached launch terminal, open the
Web UI at http://localhost:9889, or follow the
tmux guide to attach to its session.
Stop the named session when finished:
```
cao shutdown --session {session-name}
```
To stop every CAO session instead, run cao shutdown --all.

Where to go next

Operate CAO

Control-plane selection: choose the Web UI, shell
CLI, operations MCP server, or plugins.
Web UI and MCP Apps: browser and
host-rendered fleet interfaces.
Flows and workflows: scheduled runs and
multi-step pipelines.
Skills: install, scope, and author reusable agent guidance.
Memory and self-learning:
persistent cross-session memory, and the opt-in loop that turns workflow
outcomes into lessons and promoted instructions.
AI-DLC portfolio example: coordinate
parallel AI-DLC intents across repositories and isolated worktrees.
Tool restrictions: roles, allowlists, and
provider enforcement.
Updating CAO: update an installed uv tool.

Configure and integrate

Agent profiles: profile schema, discovery, provider
selection, and overrides.
HTTP API and PTY WebSocket: route-family overview and terminal
streaming contract.
Plugins: outbound events, installation, and authoring.
Provider behavior:
Kiro CLI, Claude Code,
Codex CLI, Antigravity CLI,
Hermes, Kimi CLI,
GitHub Copilot CLI,
OpenCode CLI, and
Cursor CLI.
Security policy: vulnerability reporting and deployment
guidance.

Contribute

Codebase guide: runtime surfaces, package ownership, and data
flow.
Development guide: local setup, testing, and verification.
Release guide: maintainer release process.

Contributing

See CONTRIBUTING.md and DEVELOPMENT.md
before submitting changes. Documentation changes must also follow the
documentation maintenance rule.

License

This project is licensed under the Apache License 2.0. See
LICENSE.