---
name: Swarm Orchestration
description: Pattern for 1-to-many control of agent instances using tmux and session resumption.
---

# 1-to-Many Agent Swarm Orchestration Skill

## Overview
This skill defines a pattern for an orchestrator agent to spawn, track, and control multiple sub-agent instances (a "swarm") using `tmux` for environment isolation and command-line interfaces supporting session resumption.

## Prerequisites
- `tmux` installed on the host system.
- An interactive CLI or agent tool that supports:
    - Running in a terminal.
    - Exposing a unique Session/Conversation ID.
    - Resuming sessions via targeting flags (e.g., `-conversation="<ID>"`).

## Procedure

### 1. Initialize Swarm Environment
Create a `tmux` session with multiple windows or panes, depending on the desired layout.

**Windows Layout (Clean separation & Isolation):**
```bash
tmux new-session -d -s <session_name> -n agent_1 -c /path/to/isolated/dir1
tmux new-window -t <session_name> -n agent_2 -c /path/to/isolated/dir2
...
```
Using `-c` with `tmux new-window` allows isolating the working directory of each agent.

### 2. Spawn Agents
Send execution commands to the specific windows.

```bash
tmux send-keys -t <session_name>:<window_name> "/path/to/cli --args" C-m
```

### 3. Record State
Store the mapping of `Window -> Session ID` if session resumption is needed.

## File-Based Orchestration Framework

To automate communication, use a file-based message bus.

### Directory Convention
Create a directory `swarm_framework/` in the project root:
- `comms/requests/`: For dropping request files.
- `comms/responses/`: For reading results.
- `orchestrator.py`: The polling script.
- `bootstrap.sh`: The setup script.
- `agents/`: Contains isolated directories for each agent.

### Payload Formats

**Request File (`request_<id>.json`):**
```json
{
  "request_id": "req_123",
  "sender": "master", 
  "target_agent": "orchestrator", 
  "prompt": "Your instruction here",
  "response_file": "swarm_framework/comms/responses/res_123.json"
}
```

**Response File (`res_123.json`):**
```json
{
  "request_id": "req_123",
  "status": "success",
  "output": "... captured terminal output ..."
}
```

### Notifications

For status updates and alerts not tied to a specific request-response cycle:

**Master Notifications (`comms/master_notifications.json`):**
- Used by Orchestrator to notify Master Agent about hanging sub-agents or prompts requiring attention.
- File contains a JSON list of notification objects:
```json
[
  {
    "timestamp": 1234567890.123,
    "type": "hanging|prompt",
    "agent": "grid.x",
    "message": "..."
  }
]
```
- Master Agent should periodically check this file to avoid active interruptions to user input.

**Sub-agent Approval Alerts:**
- If a sub-agent is blocked waiting for approval (e.g., "yes/no"), the Orchestrator script detects this via regex and sends a notification message directly to the Orchestrator Agent pane (`grid.0`).

### Payload Content Rules

- **Markers**: All agents MUST wrap their final answer in `===RESULT===` and `===END_RESULT===` markers to allow the system to extract the raw result and remove UI garbage.

### Decentralized Cross-Agent Communication


To support decentralized and scalable communication, agents use dedicated directories within their isolated folder in `agents/`:
- `incoming/`: For messages from other agents.
- `output/`: For messages to other agents.
- `archive/`: For processed incoming messages.

#### File Naming Convention
Files in `output/` must follow the pattern: `to_{target}_{msg_id}.json`.
- `target`: The target agent name (e.g., `agent_2`, `orchestrator`).
- `msg_id`: A unique identifier for the message.

#### Processing Flow
1. **Source Agent** writes message to its `output/` directory as a `.tmp` file and renames it to `.json` when complete.
2. **Orchestrator Watcher Thread** detects the `.json` file, extracts the target, and moves the file to the target agent's `incoming/` directory, renaming it to `from_{source}_{msg_id}.json`.
3. **Target Agent Watcher Thread** detects the file in `incoming/`, moves it to `archive/`, and notifies the agent via `tmux send-keys` to read the file.

#### Mapping
The orchestrator maps `tmux` window/pane names (e.g., `grid.1`) to directory names (e.g., `agent_1`) using a mapping function to ensure correct file routing.

## Communication Boundaries Rules

To maintain clear boundaries and prevent Master Agent overload, the following rules are enforced by `orchestrator.py`:

1.  **Master Agent** cannot be triggered via file request. Results or prompts meant for Master must be saved to `comms/master_notifications.json`.
2.  **Sub-agents** can trigger **Sub-agents** and **Orchestrator Agent**.
3.  **Master Agent** can trigger **Orchestrator Agent** ONLY.
4.  **Do not print blocking prompts or clarification requests to the console.** All agents (except Master when interacting with user) MUST raise prompts in their `output/` folder or log to `master_notifications.json` to inform upstream. Console output is not visible to users.

Ensure all request files populate the `"sender"` field!