Swarm Orchestration Framework

This framework allows you to control a swarm of $N$ agents with isolated environments via file operations.

Setup

Run the bootstrap script to create the tmux session, spawn agents, and start the orchestrator:

cd swarm_framework
chmod +x bootstrap.sh
./bootstrap.sh <N>

Replace <N> with the desired number of agents (default is 4).

Isolation

Each agent runs in its own directory: swarm_framework/agents/agent_N/. This isolates their working directory and local state if they store it there.

Usage

1. Bootstrap: Run the bootstrap script to create the swarm environment and start the Master Agent.

   ./bootstrap.sh <number_of_agents>

   Default is 4 agents if not specified. This script will start the Master Agent (jetski-cli) in the foreground. Exit the Master Agent (Ctrl+D or type exit) to stop the swarm and cleanup all resources.

1. Monitor: Open another terminal and attach to the tmux session to see sub-agents:

   tmux attach -t jetski_swarm

2. Send Request: Drop JSON request files into comms/requests/.

Format:

{
  "request_id": "req_123",
  "target_agent": "agent_1",
  "prompt": "Hello",
  "response_file": "swarm_framework/comms/responses/res_123.json"
}

Note: The target_agent should be the window name (e.g., agent_1, agent_2).

Control Actions

You can control the swarm lifecycle by sending requests with type: "control".

Actions:

• create: Spawn a new agent window and directory.
• kill: Remove an agent window.
• clear: Clear agent screen (visual).
• resume: Resume a session by ID.

Examples:

Create Agent:

{
  "request_id": "req_create",
  "type": "control",
  "action": "create",
  "target_agent": "agent_new",
  "response_file": "swarm_framework/comms/responses/res_create.json"
}

Kill Agent:

{
  "request_id": "req_kill",
  "type": "control",
  "action": "kill",
  "target_agent": "agent_new",
  "response_file": "swarm_framework/comms/responses/res_kill.json"
}

Clear Screen:

{
  "request_id": "req_clear",
  "type": "control",
  "action": "clear",
  "target_agent": "agent_1",
  "response_file": "swarm_framework/comms/responses/res_clear.json"
}

Resume Session:

{
  "request_id": "req_resume",
  "type": "control",
  "action": "resume",
  "target_agent": "agent_1",
  "conversation_id": "CONV_ID_HERE",
  "response_file": "swarm_framework/comms/responses/res_resume.json"
}

Cleanup

To clear the CLI screen for a specific agent (visually cleaning up the window):

./clear_pane.sh <target_agent>

Example: ./clear_pane.sh agent_1

Note: This preserves the session ID and conversation history; it only clears the visual terminal display.

Components

• bootstrap.sh: Initializes the environment.
• orchestrator.py: The background polling script.
• clear_pane.sh: Script to clear agent screen.
• SKILL.md: The skill definition.
• comms/: Communication directories.
• agents/: Isolated working directories for agents.