CLI Agent Orchestrator (CAO)

English | 简体中文

📚 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:

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.

1. Install the built-in supervisor profile:

cao install code_supervisor

1. In terminal A, start the local server and leave it running:

cao-server

1. In terminal B, change to the project directory the agents should work in,

cd /path/to/your/project
   cao launch --agents code_supervisor

1. Observe the supervisor in the attached launch terminal, open the

1. 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

• Web UI and MCP Apps: browser and

• Flows and workflows: scheduled runs and

• Skills: install, scope, and author reusable agent guidance.
• Memory and self-learning:

• AI-DLC portfolio example: coordinate

• Tool restrictions: roles, allowlists, and

• Kubernetes deployment: run a supervisor and worker fleet on

• Updating CAO: update an installed uv tool.

Configure and integrate

• Agent profiles: profile schema, discovery, provider

• HTTP API and PTY WebSocket: route-family overview and terminal

• Agent plugins: installing portable Agent Plugins

• Event plugins: outbound events, installation, and authoring.
• Provider behavior:

• Security policy: vulnerability reporting and deployment

Contribute

• Codebase guide: runtime surfaces, package ownership, and data

• 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.