CLI Agent Orchestrator: Running Claude Code and Codex as Coordinated tmux Workers
Multi-agent orchestration for AI coding CLIs — Claude Code, Kiro, Codex, and more, coordinated in isolated tmux sessions
At a glance
- What is it?
- CAO is a Python supervisor layer over AI coding CLIs. It launches each agent as a real CLI process inside its own tmux session, then gives one supervisor tools to delegate work. The design keeps native provider auth and capabilities, at the cost of a local server and tmux as hard prerequisites.
- Who is it for?
- Adopt CAO if you already run one of the twelve supported provider CLIs and want a supervisor to fan work out to specialists without giving up native provider authentication. Do not adopt it if you cannot run tmux 3.3 or later on the machine, or if you expect a single binary with no local server.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap CAO fills between one CLI and a team of them
A single Claude Code or Codex session is one conversation with one context window. The moment a task splits into a frontend change, a migration and a test suite, you either run three terminals and copy state between them by hand, or you accept serial execution. CAO's stated purpose is the first problem: it coordinates multiple AI coding CLIs so a supervisor can delegate work to specialist agents in parallel or sequence. The intended user is an engineer who already has a provider CLI installed and authenticated, and who wants delegation without rewriting their workflow around a new agent runtime. CAO does not replace the CLI. The README is explicit that agents remain full CLI processes with their native authentication and capabilities. That is the whole pitch: orchestration as a layer, not a substitute.
cao-server, tmux sessions, and what the supervisor actually controls
The runtime has three visible parts. A local cao-server process runs on your machine. Provider CLIs start inside isolated terminal sessions, which the repository topics and prerequisites identify as tmux. A supervisor agent gets tools for coordinating workers. The README points to CODEBASE.md for the runtime architecture and package layout, so the fine-grained data flow is not in the material available here; what is confirmable is the shape: server plus terminal sessions plus a tool-using supervisor. Isolation is the reason tmux is a prerequisite rather than an implementation detail. Each worker keeps its own terminal state, so a supervisor can address one session without disturbing another. The README lists two control surfaces beyond the attached terminal: a Web UI at http://localhost:9889 and direct tmux attachment. It also documents an HTTP API and PTY WebSocket, described as a route-family overview and terminal streaming contract. That streaming contract is what lets a browser mirror a terminal without the agent being aware of it.
Install and first launch, with the provider caveat
Prerequisites are Python 3.10 or later, tmux 3.3 or later, uv, and at least one supported provider CLI authenticated before you launch 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
The README notes a tagged release is available from PyPI as cli-agent-orchestrator, and that updating an existing installation is `cao update`. The first supervisor launch is four steps. Install the built-in profile with `cao install code_supervisor`. In terminal A, run `cao-server` and leave it running. In terminal B, change to the project directory the agents should work in and run `cao launch --agents code_supervisor`. Stop the session with `cao shutdown --session {session-name}`, or `cao shutdown --all` for every CAO session. The caveat is stated plainly in the README: the unqualified commands use CAO's default Kiro CLI provider. If you installed Claude Code or Codex instead, the focused provider guide supplies the override while the sequence stays the same. Twelve providers are listed, including Antigravity, Hermes, Kimi, MiniMax Code, GitHub Copilot CLI, OpenCode, Oh My Pi, Cursor CLI and Grok Build CLI.
Where the tmux dependency becomes an operational constraint
tmux 3.3 or later is not a soft requirement. It is the substrate. That has consequences the README does not paper over. Anything that breaks terminal multiplexing breaks CAO: a stripped container image without tmux, a remote host where you cannot keep a server process alive, a Windows environment without a tmux equivalent. The cao-server is also a long-running local process, so the deployment story is a machine you control, not a serverless function. The README does address scale-out separately, linking a Kubernetes example for running a supervisor and worker fleet on Amazon EKS with shared workspace, per-pod state and credential delivery. That example is the escape hatch for the single-machine assumption, and it is worth reading before you assume CAO is laptop-only. The other constraint is provider coupling. Because agents are real CLI processes with native authentication, CAO inherits each provider's own limits, rate limits and authentication failure modes. CAO cannot paper over a provider CLI that is not logged in. The README's insistence on authenticating the provider before launching CAO is a symptom of that inheritance, not a formality.
Profiles, skills, memory and the opt-in learning loop
Configuration is organised around agent profiles. The profile documentation covers schema, discovery, provider selection and overrides, which is where you encode which provider a given role uses. Skills are reusable agent guidance that can be installed and scoped. Memory is described as persistent cross-session memory. Self-learning is separate and opt-in: it turns workflow outcomes into lessons and promoted instructions. That distinction matters. Persistent memory and automatic promotion of lessons are different risk profiles, and grouping them would be a mistake. Tool restrictions get their own document covering roles, allowlists and provider enforcement. Flows and workflows cover scheduled runs and multi-step pipelines, so CAO is not limited to interactive supervision. The AI-DLC portfolio example coordinates parallel intents across repositories and isolated worktrees, which is the clearest published illustration of what parallel delegation looks like in practice.
How this differs from a single agent framework
The obvious alternative is a framework where agents are library objects in one process, sharing a runtime and a memory store, with tools defined as Python functions. CAO takes the opposite approach. It does not host the model or the agent loop at all. The agent loop belongs to Claude Code, Codex, Kiro or whichever CLI you installed, and CAO coordinates those processes through terminal sessions and a supervisor tool interface. The practical difference is authentication and capability inheritance. A library framework asks you to bring an API key and reimplement whatever the CLI already does. CAO asks you to install and log into the CLI first, then delegates to it. The trade runs the other way too: a library framework can inspect and mutate agent state directly, while CAO's coordination goes through a terminal session boundary and an HTTP and WebSocket surface. If your work depends on reading an agent's internal state mid-run, that boundary is friction. If your work depends on the provider's own tooling, permissions and login, the boundary is the point.
Version cadence, licence and what to check before adopting
The repository shows three releases in roughly two months: v2.3.0 in July 2026, v2.4.1 in August, and v2.5.0 on 2026-08-28, with the last push on 2026-09-10. That cadence means the surface documented today may shift within a release or two, and the README's own updating guide notes source-aware behaviour and edge cases, implying that how you installed CAO affects how it updates. The licence is Apache-2.0. That permits commercial and internal use and includes an explicit patent grant, with the usual obligations around notices and stating changes. It is not legal advice; check the LICENSE file and your own policy. The README also flags a documentation maintenance rule in CODEBASE.md for anyone changing docs, which is a signal that docs are treated as part of the contract rather than an afterthought. For a project that coordinates other tools, that matters more than usual, because a stale provider guide sends you into a launch that fails for reasons CAO itself does not explain.
Editorial conclusion
Adopt CAO if you already run one of the twelve supported provider CLIs and want a supervisor to fan work out to specialists without giving up native provider authentication. Do not adopt it if you cannot run tmux 3.3 or later on the machine, or if you expect a single binary with no local server. Before committing, verify three things yourself: that your chosen provider CLI is authenticated outside CAO, that the supervisor profile you install matches the provider you actually use (the README's unqualified commands default to Kiro CLI), and that the Web UI port 9889 is free or reconfigured.
Community notes