How awslabs/cli-agent-orchestrator works
Project Type and Purpose
• CAO is a command-line, multi-agent orchestration system built in Python.
• It manages collaborative AI “agents” via tmux sessions and an HTTP MCP (Model Context Protocol) server.
• Primary use cases: hierarchical task delegation, parallel/ sequential workflows, scheduled flows.
File Structure
• Top-level folders:
• src/cli_agent_orchestrator – core Python package
– cli/commands & cli/main.py – command-line interface
– mcp_server/ – HTTP server, REST API, models, routing
– api/ – CLI exposes its own internal API commands
– clients/ – tmux and database drivers
– services/ – business logic for sessions, flows, inbox, cleanup
– providers/ – adapters for external LLM-in-CLI tools (Claude Code, Amazon Q)
– models/ – domain objects (AgentProfile, Session, Flow, Inbox)
– utils/ – shared utilities (logging, templates, terminal helpers)
• Other files:
• tmux-install.sh, pyproject.toml, uv.lock – build/deploy config
README Insights
• Central components described: CLI front-end, local MCP HTTP server, tmux session manager, agent store.
• Core orchestration patterns: handoff (sync), assign (async), send_message (inbox).
• Flows subsystem: cron-like scheduler that posts jobs to the MCP server.
Relationships & Data Flows
1. User → CLI
2. CLI → MCP Server (HTTP REST)
3. MCP Server ↔ Database (state: sessions, inbox, flows)
4. MCP Server → tmux client (spawn new sessions or send commands)
5. tmux agent processes → MCP Server (via REST calls)
– Handoff, assign, send_message tools embed HTTP calls
6. Scheduler (flows) → MCP Server → tmux
7. Agents ↔ Agents via MCP Server inbox
Architectural Patterns & Design Principles
• Separation of Concerns: CLI front-end, API server, session orchestration, persistence, adapters
• Modular layering: cli → api → services → clients
• Isolation pattern: one tmux session per agent for context separation
• Observer/Message-Queue: inbox queuing for send_message, assign callbacks
• MVC-like structure inside mcp_server (models, server, utils)
Technologies & Frameworks to Annotate
• Python 3.x, pyproject.toml (Poetry/UV packaging)
• HTTP server (FastAPI or Flask-style via mcp_server/server.py)
• tmux CLI wrapper
• SQLite or file-based DB via clients/database.py
• Cron scheduler via Python (services/flow_service.py)
• Markdown-based agent profiles