Agent Orchestrator MCP Server

A Model Context Protocol (MCP) server that enables a master Gemini CLI agent to spawn, orchestrate, and manage multiple sub-agents within tmux sessions.

Designed for OpenClaw and Gemini CLI environments.

Features

• Tmux-based Isolation: Each sub-agent runs in its own dedicated tmux pane.
• Session Isolation: Complete separation of workspaces and event logs per execution session.
• Actor Model Communication: Decentralized, asynchronous messaging using per-agent and master inboxes.
• Auto-Inception: Sub-agents are automatically prompted with their role and protocol upon startup.
• Native Gemini CLI: Sub-agents run actual gemini CLI instances with configurable models.

Architecture

Sessions

Each time a user runs gemini, a new session is created with a unique ID. Sessions are fully isolated — agents in Session A cannot see or send messages to agents in Session B. A user can run as many sessions as they like in parallel.

graph TD
    User["User"]

    subgraph SessionA["Session A  (.agents/sessions/uuid-a/)"]
        MA["Master Agent<br/>(Gemini CLI)"]
        MA --> SA1["Sub-Agent 1"]
        MA --> SA2["Sub-Agent 2"]
        MA --> SAN["Sub-Agent N"]
    end

    subgraph SessionB["Session B  (.agents/sessions/uuid-b/)"]
        MB["Master Agent<br/>(Gemini CLI)"]
        MB --> SB1["Sub-Agent 1"]
        MB --> SB2["Sub-Agent 2"]
    end

    User -->|"runs"| MA
    User -->|"runs separately"| MB

    SessionA -. "fully isolated" .- SessionB

Inside a Session

Within a session the master agent spawns sub-agents into tmux panes. All communication is routed through append-only JSONL mailbox files. Every component — the master, each sub-agent, and the MCP server itself — can read and write without holding any in-process state.

graph TD
    Master["Master Agent<br/>(Gemini CLI + MCP)"]

    subgraph Tmux["tmux session: openclaw-agents"]
        P1["Pane — Sub-Agent 1<br/>(Gemini CLI)"]
        P2["Pane — Sub-Agent 2<br/>(Gemini CLI)"]
        PN["Pane — Sub-Agent N<br/>(Gemini CLI)"]
    end

    subgraph FS[".agents/sessions/&lt;session_id&gt;/"]
        MI["master_inbox.jsonl<br/>(messages for Master)"]
        D1["agents/agent-1/<br/>inbox.jsonl"]
        D2["agents/agent-2/<br/>inbox.jsonl"]
        DN["agents/agent-N/<br/>inbox.jsonl"]
    end

    Master -->|"agent_create → spawns"| P1
    Master -->|"agent_create → spawns"| P2
    Master -->|"agent_create → spawns"| PN

    Master -->|"send_message"| D1
    Master -->|"send_message"| D2

    P1 <-->|"wait_for_command"| D1
    P2 <-->|"wait_for_command"| D2
    PN <-->|"wait_for_command"| DN

    P1 -->|"send_message(target=master)"| MI
    P2 -->|"send_message(target=master)"| MI
    PN -->|"send_message(target=master)"| MI

    Master -->|"read_inbox"| MI

Communication Patterns

All communication is file-based and append-only. There are four routing modes, shown in order below.

sequenceDiagram
    participant Master
    participant MI as master_inbox.jsonl
    participant Inbox1 as agent-1/inbox.jsonl
    participant Agent1 as Sub-Agent 1
    participant Inbox2 as agent-2/inbox.jsonl
    participant Agent2 as Sub-Agent 2

    Note over Master,Agent2: 1 — Master sends a task to an agent
    Master->>Inbox1: send_message(payload, target="agent-1")
    Agent1->>Inbox1: wait_for_command (polls every 500 ms)
    Inbox1-->>Agent1: task + next_cursor

    Note over Master,Agent2: 2 — Agent reports result to master
    Agent1->>Agent1: execute task
    Agent1->>MI: send_message(result, target="master")
    Master->>MI: read_inbox(cursor)
    MI-->>Master: messages

    Note over Master,Agent2: 3 — Agent sends a targeted peer message
    Agent1->>Inbox2: send_message(data, target="agent-2")
    Agent2->>Inbox2: wait_for_command (polls)
    Inbox2-->>Agent2: event from Agent 1

    Note over Master,Agent2: 4 — Agent broadcasts to all peers
    Agent2->>Inbox1: send_message(data, target="all")
    Agent2->>MI: send_message(data, target="all")
    Agent1->>Inbox1: wait_for_command (polls)
    Inbox1-->>Agent1: broadcast event

Prerequisites

Before running this server, ensure you have the following installed on your system:

• tmux (Required): This server relies heavily on tmux for process isolation and pane management.
• Node.js (v18+): Required to run the MCP server.
• Gemini CLI (Optional): If you plan to spawn standard Gemini agents, the gemini command should be in your PATH.

Installation & Usage

1. Install as Gemini Extension

The easiest way to use this orchestrator is to install it directly to your Gemini CLI:

gemini extension install --auto-update https://github.com/kkweon/agent-orchestrator-mcp

2. Policy Configuration (Recommended)

To allow the master agent to manage sub-agents without constant confirmation prompts, you should install the security policy.

mkdir -p ~/.gemini/policies
# If you cloned the repo:
cp policies/agent-orchestrator.toml ~/.gemini/policies/
# Or download directly:
curl -sSL https://raw.githubusercontent.com/kkweon/agent-orchestrator-mcp/main/policies/agent-orchestrator.toml -o ~/.gemini/policies/agent-orchestrator.toml

3. Standalone Execution (via npx)

You can also run the MCP server directly using npx, which is useful for testing or manual configuration:

npx @kkweon/agent-orchestrator-mcp

Configuration (gemini-extension.json)

If you need to configure it manually in your gemini-extension.json:

{
  "mcpServers": {
    "orchestrator": {
      "command": "npx",
      "args": ["-y", "@kkweon/agent-orchestrator-mcp"]
    }
  }
}

🛠️ Tools Reference

Orchestrator Tools (For Master Agent)

Use these tools to manage your workforce.

| Tool Name | Description | Parameters | |-----------|-------------|------------| | agent_create | Spawns a new sub-agent in a split tmux pane. It automatically injects the runner loop and inception prompt. | name (string): Human-readable namerole (string): Specific role (e.g., "coder", "reviewer")model (string, optional): Specific Gemini model to use | | agent_list | Lists all active agents in the current session. | (None) | | send_message | Sends a message to one or more agents. Use target="all" to broadcast. | agent_id (string): Sender's agent ID (use 'master' if orchestrator is sending)message (object): Arbitrary JSON payloadtarget (string/array): 'all', 'master', or agent UUID(s) | | read_inbox | Non-blocking read of messages from an inbox. Use agent_id='master' for orchestrator. | agent_id (string): Target inbox ('master' or agent UUID)cursor (number, optional): Line index to resume from | | agent_delete | Terminates a sub-agent and kills its tmux pane. | agent_id (string): Target agent's UUID |

Internal Protocol Tools (For Sub-Agents)

These tools are used automatically by the sub-agents to communicate with the orchestrator. You rarely need to call them manually.

• wait_for_command: Long-polling endpoint for sub-agents to fetch new tasks from their inbox.
• send_message: Endpoint for sub-agents to report logs, progress, and results (with target="master") or communicate with peers.

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

License

MIT