CLI Agent Orchestrator (CAO) provides a lightweight system for managing multiple AI agent sessions within tmux terminals, enabling sophisticated multi-agent collaboration through a Model Context Protocol (MCP) server. It addresses the need for complex problem-solving by implementing a hierarchical multi-agent system where a supervisor agent coordinates specialized worker agents, allowing for efficient task delegation, context preservation, and flexible workflow patterns. This system is designed for engineers, researchers, and power users who require robust orchestration of CLI-based AI agents for collaborative development and complex task execution.

How It Works

CAO employs a hierarchical orchestration model, with a supervisor agent managing overall workflow and delegating tasks to specialized worker agents. Each agent operates within an isolated tmux session, ensuring context separation while facilitating seamless communication via MCP servers. Intelligent task delegation automatically routes tasks to appropriate specialists based on project requirements and expertise. The system supports three core orchestration patterns: Handoff (synchronous task transfer), Assign (asynchronous task spawning for parallel execution), and Send Message (direct communication with existing agents), enabling both sequential coordination and parallel processing for optimized development speed and quality.

Quick Start & Requirements

• Prerequisites: tmux (version 3.3 or higher), uv.
• Installation:
  • Install tmux: bash <(curl -s https://raw.githubusercontent.com/awslabs/cli-agent-orchestrator/refs/heads/main/tmux-install.sh)
  • Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh
  • Install CAO: uv tool install git+https://github.com/awslabs/cli-agent-orchestrator.git@main --upgrade
• Agent Installation: cao install <agent_name> (e.g., code_supervisor, developer, reviewer), local file, or URL. Provider selection (e.g., q_cli, kiro_cli, codex) is supported.
• Running CAO: Start the server with cao-server. Launch agents with cao launch --agents <agent_name>. Shutdown sessions with cao shutdown --all or cao shutdown --session <session_name>.
• Links: CODEBASE.md, docs/agent-profile.md, docs/codex-cli.md, docs/api.md.

Highlighted Details

• Hierarchical Orchestration: Supervisor agent manages workflow and delegates tasks to specialized worker agents.
• Session Isolation: Agents run in isolated tmux sessions with context separation via MCP servers.
• Flexible Workflow Patterns: Supports Handoff (synchronous), Assign (asynchronous), and Send Message (direct communication).
• Scheduled Runs (Flows): Automated execution of agent workflows based on cron expressions.
• Advanced CLI Integration: Integrates with features from Claude Code and Amazon Q Developer CLI.
• Codex CLI Provider: Enables orchestration of Codex agents using existing ChatGPT subscriptions without API migration.
• REST API: cao-server exposes APIs for custom orchestration patterns.
• Working Directory Support: Optional explicit directory specification for agent operations.

Maintenance & Community

No specific details regarding contributors, sponsorships, community channels (Discord/Slack), or roadmap were found in the provided README.

Licensing & Compatibility

This project is licensed under the Apache-2.0 License. No explicit restrictions for commercial use or closed-source linking were noted.

Limitations & Caveats

Working directory support is disabled by default to prevent potential agent hallucination issues with the Q CLI's context handling; users requiring explicit directory control must enable it via export CAO_ENABLE_WORKING_DIRECTORY=true. The system requires tmux version 3.3 or higher.