# awslabs/cli-agent-orchestrator architecture

> Architecture diagram of the GitHub repository awslabs/cli-agent-orchestrator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/awslabs/cli-agent-orchestrator
- Repository: https://github.com/awslabs/cli-agent-orchestrator

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "CLI Layer"
    CLI["CLI Front-end"]:::service
    Commands["CLI Command Handlers"]:::service
    APIEntry["Internal CLI API Entry Point"]:::service
    CLI --> Commands
    Commands --> APIEntry
  end

  subgraph "MCP Server"
    Server["MCP HTTP Server"]:::service
    Models["MCP Server Models"]:::service
    Utils["MCP Server Utilities"]:::service
    Server --> Models
    Server --> Utils
    APIEntry -->|"REST API: /sessions, /messages"| Server
  end

  subgraph "Service Layer"
    SessionService["Session Orchestration Service"]:::service
    FlowService["Flow Scheduler Service"]:::service
    InboxService["Inbox Service"]:::service
    CleanupService["Cleanup Service"]:::service
    TerminalService["Terminal Service"]:::service
    Server --> SessionService
    Server --> FlowService
    Server --> InboxService
    Server --> CleanupService
    Server --> TerminalService
  end

  subgraph "Clients & Database"
    DBClient["Database/State Store"]:::db
    TmuxClient["tmux Session Manager"]:::runtime
    Server -->|"DB read/write"| DBClient
    SessionService -->|"spawn sessions"| TmuxClient
  end

  subgraph "Agent Runtime Environments"
    AgentEnv["Agent Runtime Environments"]:::runtime
    TmuxClient -->|"tmux create-session & send keys"| AgentEnv
    AgentEnv -->|"HTTP calls: handoff/assign/send_message"| Server
  end

  subgraph "Flows Scheduler"
    FlowService -->|"cron trigger"| Server
  end

  subgraph "Agent Store & Utilities"
    AgentStore["Agent Store (markdown profiles)"]:::storage
    ProfilesUtil["Agent Profiles Utility"]:::util
    TemplateUtil["Template Loader Utility"]:::util
    AgentStore --> ProfilesUtil
    AgentStore --> TemplateUtil
    ProfilesUtil --> APIEntry
    TemplateUtil --> SessionService
  end

  subgraph "External Provider Adapters"
    Providers["External Provider Adapters"]:::ext
    Server --> Providers
    AgentsToProviders["Agents ↔ Providers"]:::ext
    AgentEnv --> AgentsToProviders
  end

  %% Click Events
  click CLI "https://github.com/awslabs/cli-agent-orchestrator/blob/main/src/cli_agent_orchestrator/cli/main.py"
  click Commands "https://github.com/awslabs/cli-agent-orchestrator/tree/main/src/cli_agent_orchestrator/cli/commands/"
  click APIEntry "https://github.com/awslabs/cli-agent-orchestrator/blob/main/src/cli_agent_orchestrator/api/main.py"
  click Server "https://github.com/awslabs/cli-agent-orchestrator/blob/main/src/cli_agent_orchestrator/mcp_server/server.py"
  click Models "https://github.com/awslabs/cli-agent-orchestrator/blob/main/src/cli_agent_orchestrator/mcp_server/models.py"
  click Utils "https://github.com/awslabs/cli-agent-orchestrator/blob/main/src/cli_agent_orchestrator/mcp_server/utils.py"
  click DBClient "https://github.com/awslabs/cli-agent-orchestrator/blob/main/src/cli_agent_orchestrator/clients/database.py"
  click TmuxClient "https://github.com/awslabs/cli-agent-orchestrator/blob/main/src/cli_agent_orchestrator/clients/tmux.py"
  click SessionService "https://github.com/awslabs/cli-agent-orchestrator/blob/main/src/cli_agent_orchestrator/services/session_service.py"
  click FlowService "https://github.com/awslabs/cli-agent-orchestrator/blob/main/src/cli_agent_orchestrator/services/flow_service.py"
  click InboxService "https://github.com/awslabs/cli-agent-orchestrator/blob/main/src/cli_agent_orchestrator/services/inbox_service.py"
  click CleanupService "https://github.com/awslabs/cli-agent-orchestrator/blob/main/src/cli_agent_orchestrator/services/cleanup_service.py"
  click TerminalService "https://github.com/awslabs/cli-agent-orchestrator/blob/main/src/cli_agent_orchestrator/services/terminal_service.py"
  click AgentStore "https://github.com/awslabs/cli-agent-orchestrator/tree/main/src/cli_agent_orchestrator/agent_store/"
  click ProfilesUtil "https://github.com/awslabs/cli-agent-orchestrator/blob/main/src/cli_agent_orchestrator/utils/agent_profiles.py"
  click TemplateUtil "https://github.com/awslabs/cli-agent-orchestrator/blob/main/src/cli_agent_orchestrator/utils/template.py"
  click Providers "https://github.com/awslabs/cli-agent-orchestrator/tree/main/src/cli_agent_orchestrator/providers/"

  %% Styles
  classDef service fill:#cce5ff,stroke:#333,stroke-width:1px;
  classDef db fill:#ccffcc,stroke:#333,stroke-width:1px;
  classDef runtime fill:#e0e0e0,stroke:#333,stroke-width:1px;
  classDef ext fill:#ffddb3,stroke:#333,stroke-width:1px;
  classDef storage fill:#ccffcc,stroke:#333,stroke-width:1px;
  classDef util fill:#f0f0f0,stroke:#333,stroke-width:1px;
```
