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.
📚 Documentation — guides, reference, and two interactive courses.
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, MiniMax Code, GitHub Copilot CLI, OpenCode CLI, Oh My Pi(OMP) CLI, Cursor CLI, or Grok Build 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.
- Launch decisions: local routing settings and content-free records.
- Skills: install, scope, and author reusable agent guidance.
- Skills lifecycle example: install, discover, load, apply, update, and remove a reusable skill in an isolated home.
- 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.
- Cross-zone robot transport: coordinate simulated transport, measured custody handoffs, and independent checks.
- Self-hosted decision model: run the open
JevK5-4B decision model locally or on AWS (CDK), behind a loopback-only
/v1/systemoneAPI. - Tool restrictions: roles, allowlists, and provider enforcement.
- Kubernetes deployment: run a supervisor and worker fleet on Amazon EKS, with shared workspace, per-pod state, and credential delivery.
Configure and integrate
- Ephemeral agents: opt-in create-only profiles and their limits.
- Agent profiles: profile schema, discovery, provider selection, and overrides.
- HTTP API and PTY WebSocket: route-family overview and terminal streaming contract.
- Agent plugins: installing portable Agent Plugins
1.0.0 packages, and CAO's own operator and contributor packages. Every
surface — the CLI, TUI, web panel, and the
/plugins*HTTP routes — is built but gated off by default pending a naming decision. SetCAO_AGENT_PLUGINS_ENABLEDto open it; until then the routes answer404, exactly as an unregistered path would. - Event plugins: outbound events, installation, and authoring.
- Provider behavior: Kiro CLI, Claude Code, Codex CLI, Antigravity CLI, Hermes, Kimi CLI, MiniMax Code, GitHub Copilot CLI, OpenCode CLI, Oh My Pi(OMP) CLI, Cursor CLI, and Grok Build CLI.
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.