04

Running Your Own Agents

From install to your first multi-agent session in 5 minutes.

From Zero to Multi-Agent in 5 Minutes

⚠️
Prerequisites

Python 3.10+, tmux, and at least one AI CLI agent (Claude Code, Kiro CLI, or Codex). CAO requires macOS or Linux — tmux is not available on Windows.

Six commands take you from nothing installed to a fully running multi-agent session:

1
Install

uv tool install cli-agent-orchestrator — Downloads the CAO binary and all dependencies in one shot.

2
Start the server

cao-server — Launches the FastAPI orchestration service. Keep this terminal open; everything else talks to it.

3
Launch a session

cao launch --agents code_supervisor --session-name demo --provider claude_code — Creates a tmux session and starts the supervisor agent inside it. The session is named cao-demo — CAO prefixes every session with cao-.

4
Observe

cao session status cao-demo --workers — Shows the session state: which agents are running, idle, or finished.

5
Send more work

cao session send cao-demo "Add unit tests" — Types a new task straight into the supervisor's terminal. The agent must be idle; if it is still working, the command tells you to wait.

6
Shut down

cao shutdown --all — Terminates all agent tmux sessions and cleans up terminal records. The server keeps running.

i
Keeping up to date

Run cao update to pull the latest version. Use cao profile list to see all available agent profiles on your machine.

Anatomy of a Profile

Profiles are markdown files with YAML frontmatter. They live in a standard directory:

~/.aws/cli-agent-orchestrator/
agent-context/ — profiles installed by cao install
code_supervisor.md
developer.md
reviewer.md
agent-store/ — profiles you author locally
db/ — session state and message history
logs/ — server logs; per-terminal output in logs/terminal/
memory/ — persistent context between sessions
profile 
---
name: code_supervisor
description: Coding Supervisor Agent
provider: claude_code
role: supervisor
---
You are a supervisor. Delegate to
`developer` and `reviewer` profiles.
Plain English
name — Unique identifier passed to --agents
description — Human label shown in cao profile list
provider — Which AI CLI runs this agent (claude_code, kiro_cli, codex, etc.)
role — Determines default tool access (supervisor, developer, reviewer)
Body (below the frontmatter) — The system prompt injected into the agent at launch

The Role System

Each role grants a specific set of tools. Choose the narrowest role that fits the agent's job.

S
supervisor

Orchestrates other agents. Cannot edit files or run commands directly.

@cao-mcp-server, fs_read, fs_list
D
developer

Full execution environment. Reads, writes, runs commands, fetches URLs, and coordinates via MCP.

@builtin, fs_*, execute_bash, web_fetch, @cao-mcp-server
R
reviewer

Read-only access. Can inspect code and communicate findings but cannot modify anything.

@builtin, fs_read, fs_list, @cao-mcp-server
!
The --yolo flag

The --yolo flag removes ALL restrictions — useful for experimentation but dangerous for production. The agent can run any command including rm -rf and aws calls.

i
Provider-agnostic orchestration

Providers are interchangeable — the orchestration layer is provider-agnostic. A supervisor on Claude Code can assign workers to Kiro CLI, Codex, or any mix.

Final Check

1. You installed CAO but cao launch says "Failed to connect to cao-server". What's wrong?

You now understand how CAO works — from the supervisor-worker pattern to the orchestration tools to hands-on usage. Go build something with multiple agents.

Ready for more?

Learn about Workflows, Skills, Scheduled Flows, and the Ops MCP Server.

Advanced Features →