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

tmux new-session -d -s <session_name> -n agent1
tmux new-window -t <session_name> -n agent2
...

Grid Layout (All-in-one view):

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.

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

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

{
  "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.