---
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):**
```bash
tmux new-session -d -s <session_name> -n agent1
tmux new-window -t <session_name> -n agent2
...
```

**Grid Layout (All-in-one view):**
```bash
tmux new-window -t <session_name> -n grid
tmux split-window -t <session_name>:grid
tmux select-layout -t <session_name>:grid tiled
```

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

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

### 3. Capture Session IDs
Extract the unique identifiers generated by the agents to enable future resumption.
- Use `tmux capture-pane -p -t <target>` to read the screen.
- Look for patterns indicating Conversation IDs or session hashes.
- If not visible, trigger menus or status commands (e.g., `/` commands).

### 4. Record State
Store the mapping of `Pane/Window -> Session ID` in a persistent file (e.g., `swarm_sessions.md`) so the orchestrator can resume tracking after context breaks or restarts.

## File-Based Orchestration Framework

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

### Directory Convention
Create a directory `tmp/swarm/` in the project root:
- `requests/`: For dropping request files.
- `responses/`: For reading results.
- `scripts/`: For the orchestrator script.

### Payload Formats

**Request File (`request_<id>.json`):**
```json
{
  "request_id": "req_123",
  "target_agent": "grid.0", 
  "prompt": "Your instruction here",
  "response_file": "tmp/swarm/responses/res_123.json"
}
```

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

### Orchestrator Script
A script running in the background polls `requests/`, executes the `tmux send-keys` command, captures the results, and writes the response file.

Example implementation at: `tmp/swarm/scripts/swarm_orchestrator.py`

## General Applicability
This pattern applies to any CLI-based tool or agent system that allows isolated instances and session targeting. It is not limited to any specific project or workspace.