CLI Agent Orchestrator (CAO): a supervisor for Claude Code, Kiro and Codex in tmux sessions

The problem: one terminal, one coding CLI, one task at a time

A coding CLI is a single conversational process. You give it a task, it works, and while it works you are either watching it or waiting for it. Running two of them means two terminals and your own memory as the coordination layer: who is doing what, which one finished, which one is blocked on the other's output.

CAO's answer is to make one agent the coordinator. The README describes the shape directly: CAO "coordinates multiple AI coding CLIs so a supervisor can delegate work to specialist agents in parallel or sequence." The audience is developers who already have a working provider CLI and want a second and third one working on the same project without hand-managing terminals.

The design choice that matters is that agents stay real CLI processes. The README states that "the agents remain full CLI processes with their native authentication and capabilities." CAO does not wrap the model API, does not proxy credentials, and does not reimplement tool calling. It drives the same binaries you would run yourself, which means the behaviour you already know from Claude Code or Codex carries over, and so do their failure modes.

How CAO works: cao-server, tmux sessions, and a supervisor with tools

The runtime has three visible pieces. A local `cao-server` process runs on your machine. Provider CLIs are started inside isolated terminal sessions. A supervisor agent gets a set of tools for coordinating workers.

According to the README, the architecture and package layout are documented in CODEBASE.md, which describes "runtime surfaces, package ownership, and data flow." The README itself lists the operational surfaces: a Web UI, a shell CLI, an operations MCP server, and plugins, with control-plane selection documented separately. Agent profiles define the schema, discovery, provider selection and overrides. There is an HTTP API plus a PTY WebSocket, described as a "route-family overview and terminal streaming contract," which is the mechanism by which a browser or host-rendered interface watches a terminal that is really a tmux pane.

Two consequences follow from running through tmux rather than through an in-process SDK. First, you can attach to a session yourself and watch or type into it, which the README supports by pointing at the tmux guide. Second, the whole thing is POSIX-bound. The pyproject classifiers list MacOS and POSIX Linux only, and the comment above them is unusually candid: the package imports `fcntl`/`termios` at module scope, and no installer enforces an Operating System classifier. On Windows, the stated sequence is that pip falls back to the sdist, the sdist installs, and the first `cao` command raises, with a guard in `cli_agent_orchestrator/__init__.py` that explains why. That is a deliberate refusal, not an oversight.

Installing CAO and launching a first supervisor

Prerequisites come first: Python 3.10 or later, tmux 3.3 or later, uv, and at least one supported provider CLI that you have authenticated before launching CAO. The README lists twelve providers, including 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. Each has a focused guide covering installation and authentication.

The README's install path for the current main branch is a uv tool install:

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

For a tagged release the README directs you to `cli-agent-orchestrator` on PyPI instead. Updating an existing installation is a single command, and the README notes that `docs/updating.md` covers "source-aware behavior and edge cases," which is worth reading if you installed from git rather than from PyPI.

cao update

The first supervisor launch is four steps. Install the built-in supervisor profile, start the server in one terminal and leave it running, then launch the supervisor from the directory the agents should work in.

cao install code_supervisor
cao-server

In a second terminal:

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

The unqualified commands use CAO's default Kiro CLI provider. If you installed a different provider, the README says to follow that provider's guide for the override while keeping the same sequence. Once launched, you can watch the supervisor in the attached launch terminal, open the Web UI at `http://localhost:9889`, or attach to its tmux session. When you are done, stop the named session, or stop everything:

cao shutdown --session {session-name}
cao shutdown --all

Where CAO stops short: coordination is not containment

The most important limitation is one the README implies rather than states. CAO coordinates agents; it does not appear to constrain what they can do. Tool restrictions live in a separate document covering "roles, allowlists, and provider enforcement," and the word enforcement points at the provider, not at CAO. If you want an agent that cannot run a shell command, that property comes from the provider CLI's own configuration, and CAO is passing it through.

There is a second boundary worth naming. The project is classified as Development Status 4 - Beta in pyproject.toml. The release cadence is real (v2.5.0 on 2026-08-28, v2.4.1 on 2026-08-04, v2.3.0 on 2026-07-12), but beta status plus a dependency list that pins an upper bound on a FastMCP major version, because the code monkey-patches an internal (`create_initialization_options`), tells you the integration surface is not frozen. Upgrades can break in ways the changelog may not fully describe.

And there is a genuine wrong-tool case: if your work is one task, one agent, one sitting, CAO adds a server process, a session lifecycle, and a profile to install. The README's own flow is five steps before an agent does anything. For a single refactor, run the CLI directly.

One more caveat that the README does not resolve: it documents `cao update` but does not document rollback. If a new release regresses, the documented path back is reinstallation, not a downgrade command.

CAO versus a single provider CLI and versus a framework orchestrator

The natural alternative is just running Claude Code or Codex by hand in two terminals. That is genuinely competitive for two agents: you keep full visibility, there is no server to keep alive, and there is no profile schema to learn. What you lose is the supervisor pattern. With CAO, one agent holds the plan and dispatches; with manual terminals, you hold the plan. CAO also gives you a fleet view (Web UI, MCP Apps for host-rendered interfaces) and scheduled runs through flows and workflows, neither of which has a manual equivalent.

The other alternative is an orchestration framework that builds agents on top of a model API directly. The difference is architectural. A framework owns the agent loop, so it can enforce tool allowlists, log every step, and replay a run deterministically, but you give up the provider CLI's own features and re-authenticate against the API. CAO inverts that: it keeps the CLI as the unit of execution and orchestrates processes. You inherit each CLI's native capabilities and authentication, and you inherit its opacity too, because the coordination layer is talking to a terminal, not to a structured event stream.

A related set of projects shows up in search traffic around this name ("ComposioHQ agent orchestrator", "AI agent orchestrator"), which are not the same tool. CAO's distinguishing constraint is the tmux session as the unit of isolation, and the provider CLIs as the workers.

Maintenance, licence, and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-09-10, ten days before this writing. Releases have landed roughly monthly through mid-2026. Treat it as a project that is being worked on, with the caveat that beta classification and a monkey-patched dependency internal mean a minor-version bump can require code changes on the integration side.

The maintenance cost you own is not the Python package. It is the provider CLIs. CAO depends on twelve external CLIs, each with its own release cadence, its own authentication flow, and its own breaking changes. A CAO upgrade that looks routine can surface as a provider guide that no longer matches the installed binary. Budget for reading the focused provider guide after any CLI update, not just after `cao update`.

There is also a small housekeeping target in the Makefile for the vendored MCP Apps builder skills, pinned to a specific upstream tag and SHA. `make check-ext-apps-skills` verifies the on-disk copy still matches the pin and exits 2 when it cannot verify over the network. That is a contributor-facing concern, not an operator one, but it tells you the project vendors upstream code rather than tracking it live.

On licensing: the project is Apache-2.0, stated in both the README and pyproject.toml. The repository carries a NOTICE file, and the Makefile rewrites it when re-vendoring the ext-apps skills, which is the Apache-2.0 convention for bundled third-party work. If you redistribute CAO inside a product, the NOTICE and the vendored skills are the parts to look at. This is a description of what the files say, not legal advice.

Editorial conclusion

Adopt CAO if you already run at least one supported provider CLI interactively, you work on macOS or Linux, and you want a supervisor that fans work out to specialist agents in separate tmux sessions without giving up each CLI's native authentication. Do not adopt it on Windows (the package imports fcntl and termios at module scope and orchestrates through tmux), and do not adopt it if you expect the orchestration layer to sandbox agents for you: the README points at a separate tool-restrictions document for roles and allowlists. Before you commit, verify three things: that your provider CLI is authenticated outside CAO, that tmux 3.3 or later is on the box, and that the session name you plan to reuse is not already attached, since cao shutdown takes a session name or --all.

Frequently asked questions

Official sources

1. awslabs/cli-agent-orchestrator on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases