CLI Agent Orchestrator (CAO)

The CAO Web UI provides a dashboard for the following capabilities:

• Session dashboard: View all active sessions and their terminals.
• Terminal status: Real-time indicators (IDLE, PROCESSING, COMPLETED, ERROR).
• Terminal output: Live-streaming scrollback from agents.
• WebSocket PTY: Full interactive terminal access via /terminals/{id}/ws.
• Inbox monitoring: Monitor pending and delivered messages per terminal.
• Flow management: View, enable, disable, and check next run times for scheduled flows.
• Settings: Configure agent directories, skill directories, memory, and backend settings.
• Session control: Launch, send messages, and shut down sessions.

The cao_mcp_apps package provides the frontend UI surface for CAO's Model Context Protocol (MCP) Apps. It is designed to be browser-free and JIT-free, serving as a UI layer for MCP-capable hosts like Claude Desktop, ChatGPT, VS Code GitHub Copilot, and others.

Key characteristics:

• Single-file artifacts: Each view is built into a single, self-contained HTML file with all JS and CSS inlined. This allows hosts to load views without an external asset server.
• JIT-free: The builds target es2021 and strictly avoid eval or new Function to comply with strict Content Security Policies (CSP) that forbid unsafe-eval.
• Build-time only: While Node.js is required for development, testing, and rebuilding views, it is not required to run CAO itself. The built artifacts are shipped inside the Python wheel at src/cli_agent_orchestrator/ext_apps/apps_static/.

CAO operates as a local client-server application with several distinct entry points depending on your needs:

• cao: The primary Click-based CLI for command-line interaction (located in src/cli_agent_orchestrator/cli/).
• cao-server: The FastAPI application providing the HTTP, SSE, and WebSocket API (located in src/cli_agent_orchestrator/api/main.py).
• cao-mcp-server: An MCP server that exposes in-session supervisor and worker tools (located in src/cli_agent_orchestrator/mcp_server/).
• cao-ops-mcp-server: An MCP server that exposes external fleet-management tools (located in src/cli_agent_orchestrator/ops_mcp_server/).
• Browser Client: A bundled React UI built from web/.
• MCP App views: Specialized views built from cao_mcp_apps/ and served via ext_apps/ and the built-in plugin.

The CLI Agent Orchestrator (CAO) API is primarily served via HTTP. The default base URL for the server is http://localhost:9889.

For exhaustive details on individual HTTP operations, refer to the FastAPI OpenAPI schema and schema UI generated by cao-server when it is running. Note that OpenAPI does not cover WebSocket behavior; PTY WebSocket details are documented separately.

curl http://localhost:9889/health
curl http://localhost:9889/sessions
curl http://localhost:9889/agents/providers

The Fleet Coordinator is a layer that allows you to manage multiple CAO nodes (different machines) from a single interface. While a standard CAO installation coordinates agents on a single machine, the Fleet Coordinator allows a central coordinator to observe and command multiple cao-server instances across a network (via Tailscale, VPN, LAN, etc.) without needing to SSH into each host individually.

Key characteristics:

• Statelessness: Both the Web Panel and the AI Conductor are stateless and can be restarted at any time.
• Non-intrusive: It acts as a thin client to the existing cao-server HTTP API; no changes are required to how individual nodes run their agents.
• Dual Surfaces: You can interact with the fleet via a Web Panel (visual dashboard) or an AI Conductor (natural language control via MCP).

CAO's memory system provides agents with persistent, cross-session storage for facts, decisions, and preferences.

How it works:

1. Storage: Agents use the memory_store MCP tool to save information. CAO persists this as a Markdown wiki file in ~/.aws/cli-agent-orchestrator/memory/ and updates a SQLite metadata index.
2. Injection: At the start of a new session, CAO automatically injects relevant memories into the agent's context via a <cao-memory> block prepended to the first message.
3. Recall: Agents can explicitly look up information using the memory_recall MCP tool or the cao memory CLI.

Architecture Note: The system uses two coupled stores:

• Markdown wiki files: The content store (one file per memory key).
• SQLite (memory_metadata table): The metadata/index store and the source of truth for metadata queries (recency, usage, etc.).

CLI Agent Orchestrator (CAO) is an open-source multi-agent orchestration framework designed for AI programming CLIs such as Claude Code, Kiro CLI, Codex CLI, and others.

CAO acts as a lightweight local orchestrator that sits between you and your preferred CLI agents. It allows a supervisor Agent to start, message, and coordinate multiple worker Agents. Each worker runs as a real CLI tool within its own isolated tmux session.

Agents communicate using Model Context Protocol (MCP) primitives, specifically:

• handoff: Synchronous; waits for completion.
• assign: Asynchronous; fire-and-forget.
• send_message: Delivers a message to an Agent's inbox.

Because each agent is a full CLI process, CAO preserves the original tool's behavior, authentication methods, and advanced capabilities (like Claude Code sub-agents) that standard API wrappers often lose.

The repository is organized as follows:

• src/cli_agent_orchestrator/: Main source code
  • api/: FastAPI server
  • cli/: CLI commands
  • clients/: Database and tmux clients
  • mcp_server/: MCP server implementation
  • models/: Data models
  • providers/: Agent providers (e.g., Kiro CLI, Claude Code, Codex, etc.)
  • services/: Business logic services
  • utils/: Utility functions
• test/: Test suite (API, CLI, clients, e2e, mcp_server, models, providers, services, utils)
• docs/: Documentation
• examples/: Example workflows
• pyproject.toml: Project configuration
• uv.lock: Locked dependencies

To maintain governance, authentication scopes, and auditability, all code within mcp_server/* must interact with the Backplane state exclusively through HTTP calls to the FastAPI server at API_BASE_URL (default http://127.0.0.1:9889).

Forbidden Pattern: Directly importing state-holding modules such as clients.tmux or clients.database inside mcp_server/ or ext_apps/ is strictly prohibited. Bypassing the HTTP boundary allows mutations to escape the governance layer.

This constraint is enforced via an AST-based static analysis check. Run this test from the repository root:

uv run pytest test/test_http_only_boundary.py -v