Swarm Simulator

Run a multi-agent swarm simulation directly in Claude Code. No API keys needed. Uses real independent subagents — each population is simulated by a separate agent process that cannot see what other populations decided. Generates a beautiful HTML dashboard.

Usage: /simulate <scenario description>

Instructions

You are the orchestrator of a multi-agent swarm simulation. You coordinate the simulation, but each population is run by an independent subagent via the Agent tool. This produces genuinely independent reasoning — not one mind imagining all agents.

The user's scenario: $ARGUMENTS

Follow these steps exactly:

Step 0: Research the Scenario (parallel)

Launch 3-5 research subagents in parallel using the Agent tool. Each subagent researches a different angle:

• Agent 1: Market data, industry statistics, market size
• Agent 2: Historical precedents — similar scenarios and their outcomes
• Agent 3: Key stakeholders, competitors, and their known positions
• Agent 4: Recent news and developments related to the topic
• Agent 5: Regulatory, legal, or policy context if relevant

Each research agent should use WebSearch and return a structured summary with sources.

Spawn all research agents in a single message so they run concurrently. When they complete, synthesize their findings into a brief Research Summary for the user.

Step 1: Design Agent Populations (informed by research)

Based on the research, design 3-5 agent populations. For each define:

• Name, Count (10-30 each, 40-100 total), Personality, Goals, Behavioral bias, Variation (low/medium/high)

Also define: Environment rules, Output goal (key question to answer), Rounds (use 5).

Show the user a summary table of populations before proceeding.

Then write the simulation state file to /tmp/swarm-state.json:

{
  "scenario": "...",
  "environmentRules": "...",
  "outputGoal": "...",
  "populations": [...],
  "researchSummary": "...",
  "researchSources": [...],
  "rounds": [],
  "currentRound": 0,
  "worldState": {
    "sentimentCounts": {"positive": 0, "neutral": 0, "negative": 0},
    "stanceDistribution": {},
    "keyEvents": [],
    "populationSummaries": {}
  }
}

Step 2: Run 5 Simulation Rounds (parallel subagents)

For EACH round (1 through 5):

2a. Spawn population subagents in parallel

Launch one Agent subagent per population in a single message — all running simultaneously. This is the key innovation: each population is simulated independently and cannot see other populations' decisions for this round.

Each population subagent gets this prompt:

You are a behavioral simulation engine for ONE population group in a multi-agent simulation. You must generate realistic, psychologically diverse responses.

SCENARIO: {scenario_description}
ENVIRONMENT RULES: {environment_rules}

YOUR POPULATION: "{population_name}"
- Count: {count} individuals
- Personality: {personality}
- Goals: {goals}
- Behavioral bias: {bias}
- Variation level: {variation}

CURRENT WORLD STATE (from previous rounds):
{worldState as JSON — sentiment counts, stance distribution, key events, other population summaries}

ROUND: {round_number} of 5

VARIATION GUIDANCE:
- low: Minor differences, slight sentiment variations
- medium: Moderate diversity — some agree, some hesitant, a few dissent
- high: Wide range — strong disagreements, outliers, contrarian views

Generate decisions for each of your {count} individuals. Each agent should react to the current world state based on their personality and bias.

Return ONLY a JSON object (no markdown, no explanation):
{
  "populationName": "{population_name}",
  "decisions": [
    {
      "agentIndex": 0,
      "agentName": "A generated name for this individual",
      "observation": "What this person notices/focuses on (1-2 sentences)",
      "action": "What they decide to do (1-2 sentences)",
      "reasoning": "Why they made this choice (1 sentence)",
      "sentiment": "positive|neutral|negative",
      "stance": "short label (e.g., stay, leave, wait-and-see, protest)"
    }
  ],
  "populationSummary": "One-sentence summary of this population's overall mood and direction this round"
}

CRITICAL: Spawn ALL population agents in a SINGLE message so they run in parallel. Do not run them sequentially.

2b. Aggregate round results

When all population subagents return, read their JSON results. Then:

1. Aggregate sentiment — count positive/neutral/negative across all populations
2. Aggregate stances — merge stance distributions
3. Detect emergent events:
   • Negative sentiment ratio increased >15% from previous round
   • Positive sentiment ratio increased >15% from previous round
   • All populations converge on same dominant stance (cross-population consensus)
   • A population's dominant stance flipped from previous round
   • Any unexpected cross-group solidarity or conflict
4. Update /tmp/swarm-state.json — append the round data and update worldState
5. Show the user a round summary:

### Round {N} of 5

**Sentiment:** +{pos} / ={neu} / -{neg}
**Stances:** {stance}: {count}, ...
{For each emergent event: "⚡ **Emergent:** {event}"}
**Population highlights:**
- {pop1}: {summary}
- {pop2}: {summary}

Then proceed to the next round with the updated world state.

Step 3: Generate Report

After all 5 rounds, read the full /tmp/swarm-state.json and analyze the complete simulation. Produce a structured report with:

• Executive Summary (2-3 paragraphs directly answering the original question)
• Key Findings (5-8 findings with confidence: high/medium/low)
• Emergent Behaviors (2-4 unexpected patterns — the most valuable insights)
• Recommendations (3-5 actionable next steps)
• Confidence Score (0-100)
• Notable Agents (2-3 interesting individual agent stories from the simulation data)
• Round Summaries (key event per round)

Write the report to /tmp/swarm-state.json under a report key.

Step 4: Generate HTML Dashboard

This is the key deliverable. Write an HTML file to /tmp/swarm-report.html and open it with open /tmp/swarm-report.html.

Read the simulation data from /tmp/swarm-state.json to populate the dashboard.

The HTML dashboard should be a single self-contained file (inline CSS + JS, no external deps) with:

Header section:

• Scenario title (large)
• Stats bar: total agents, rounds, number of populations, confidence score gauge (colored: green >70, yellow 40-70, red <40)
• Badge: "Independent Subagents" to indicate real multi-agent simulation

Executive Summary card

Key Findings — numbered list with colored confidence badges (green=high, yellow=medium, red=low)

Sentiment Over Time chart — an SVG line chart showing positive/neutral/negative sentiment counts across all 5 rounds (3 colored lines: green, gray, red). X-axis = rounds, Y-axis = agent counts. Include gridlines and data point labels.

Stance Distribution — horizontal bar chart (SVG) showing final stance distribution with percentage labels

Population Breakdown — show each population's final sentiment and dominant stance as a mini card grid

Emergent Behaviors — cards with lightning bolt icon, yellow accent border

Round-by-Round Timeline — collapsible accordion sections, click to expand each round's details including per-population summaries

Agent Spotlight — cards for each notable agent with their population badge and story

Recommendations — numbered cards

Research Sources — list of sources from the research phase with links

Design requirements:

• Dark theme: background #0f172a, cards #1e293b, text #e2e8f0, accents #38bdf8
• Clean sans-serif font (system font stack)
• Rounded corners, subtle shadows
• Responsive layout (max-width 900px centered)
• Smooth transitions on accordion open/close
• Print-friendly: add @media print styles

After writing the file, open it in the browser with open /tmp/swarm-report.html.

Key Principles

• Real independence — each population is a separate subagent that cannot see other populations' current-round decisions. This produces genuinely emergent behavior.
• Parallel execution — all population agents for a round launch simultaneously. Research agents also run in parallel. This maximizes speed.
• Persistent state — /tmp/swarm-state.json tracks the full simulation state. Each round reads and updates it. The dashboard reads from it.
• Research first — ground the simulation in real data via parallel web search agents
• Realistic psychology — agents aren't uniform. Include dissent, indifference, unexpected reactions
• Emergent behavior is the value — the independence of subagents means emergent patterns are real, not imagined
• The HTML dashboard is the deliverable — make it beautiful and data-rich
• Keep the user updated — show research summary, round summaries as they complete, then deliver the dashboard