---
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",
  "target_agent": "agent_1", 
  "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 ..."
}
```