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):

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.

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):

{
  "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):

{
  "request_id": "req_123",
  "status": "success",
  "output": "... captured terminal output ..."
}