Swarma

What it does

When your agent uses it

• Tasks that involve Product metrics

Example prompts

• “/swarma”

Requirements

• Python 3
• A credential in OPENROUTER_API_KEY
• Compatibility (from SKILL.md): Python 3.11+, pip, terminal access

Workflow steps

5 steps, taken from the step headings in SKILL.md.

1. 1Understand the goal
2. 2Install
3. 3Generate the team
4. 4Run the first cycle
5. 5Run more cycles and review

What it can do on your machine

Read from SKILL.md and the folder at commit 4f62366. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • pip
  • git
  • python

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • openrouter.ai

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • OPENROUTER_API_KEY

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Python 3.11+, pip, terminal access

  From compatibility in the SKILL.md frontmatter.

Context cost

Swarma loads about 4.4k tokens when it runs. Until then it costs about 68 tokens; SKILL.md has 1,328 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~68

When it runs · the whole SKILL.md, loaded when a task matches

~4.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteMentions a .env fileSKILL.md:145

  be in the MCP `env` block. The instance `.env` is not inherited by subprocesses.

• NoteMentions a .env fileSKILL.md:202

  k-or-..." >> ~/.swarma/instances/default/.env

• NoteMentions a .env fileSKILL.md:211

  8181/mcp" >> ~/.swarma/instances/default/.env

• NoteMentions a .env fileSKILL.md:504

  Y` | Add to `~/.swarma/instances/default/.env` |

• NoteMentions a .env fileSKILL.md:505

  CP subprocess can't find key | Instance `.env` not inherited | Pass key in MCP config `env` block |

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from glitch-rabin/swarma at commit 4f62366, republished under its MIT licence (© glitch-rabin). 1,328 words, ~4,408 tokens.

name

swarma

description

Agent teams that run growth experiments and build their own playbook. GROWS loop: generate hypothesis, run experiment, observe signal, weigh verdict, stack playbook. 18 pre-built squads covering the full AARRR funnel. Your agents stop guessing and start learning.

compatibility

Python 3.11+, pip, terminal access

version

0.2.0

license

MIT

metadata.repository

https://github.com/glitch-rabin/swarma

metadata.website

https://swarma.dev

metadata.hook

a swarm runs 50 experiments while a human team runs 2

metadata.keywords

growth experiments, A/B testing, agent teams, swarm intelligence, AARRR funnel, playbook, learning agents, experiment loop, strategy evolution, self-improving

  Generate       Run         Observe       Weigh        Stack
 hypothesis --> experiment --> signal --> verdict --> playbook
     ^                                                  |
     └──────────────────────────────────────────────────┘

pip install swarma
swarma init

{
  "mcpServers": {
    "swarma": {
      "command": "swarma",
      "args": ["serve", "--mcp"],
      "env": { "OPENROUTER_API_KEY": "sk-or-..." }
    }
  }
}

pip install swarma
swarma init

# hermes config.yaml
mcp_servers:
  swarma:
    transport: stdio
    command: swarma
    args: ["serve", "--mcp"]
    env:
      OPENROUTER_API_KEY: "sk-or-..."

pip install swarma
swarma init

pip install swarma
swarma init                                        # creates instance + starter team
swarma cycle starter --topic "why do startups fail?"   # run one cycle
swarma status                                      # check costs, runs, experiments

git clone https://github.com/glitch-rabin/swarma.git
cd swarma && pip install -e .
swarma init

echo "OPENROUTER_API_KEY=sk-or-..." >> ~/.swarma/instances/default/.env

# Only needed when running 3+ teams
echo "QMD_ENDPOINT=http://localhost:8181/mcp" >> ~/.swarma/instances/default/.env

pip install swarma
swarma init --yes

swarma team create growth-lab \
  --from-goal "optimize landing page conversion for our B2B SaaS" \
  --context "developer tools company, 500 free users, 2% conversion to paid" \
  --budget 30

swarma team show growth-lab

swarma cycle growth-lab

Running cycle: growth-lab
  flow: researcher -> copywriter -> judge
  agents: ['researcher', 'copywriter', 'judge']

                              Cycle: growth-lab
  Agent      Model              Cost       Output Preview
  researcher sonar-pro          $0.000384  **Topic:** 52% of executives...
  copywriter qwen3.5-plus-02-15 $0.000746  [A] We sent 4,382 cold emails...
  judge      mistral-nemo       $0.000416  **Hook Variations:** A: "Did...

  duration: 43.9s | total cost: $0.001546 | agents: 3

swarma cycle growth-lab                    # run another cycle
swarma cycle growth-lab --topic "specific angle"  # with a topic
swarma status                              # check progress

# Single cycle
swarma cycle hook-lab

# With a specific topic
swarma cycle hook-lab --topic "AI agents are commoditizing"

# Continuous (teams with cron schedules run automatically)
swarma run

# Continuous with API server
swarma run --port 8282

# Log a single metric
swarma metric log hook-lab copywriter 4.2 --metric ctr_pct

# Attach to a specific experiment
swarma metric log hook-lab copywriter 127 --metric impressions --exp 3

# Add a note
swarma metric log hook-lab copywriter 5.1 --metric ctr_pct --note "from linkedin analytics"

# Bulk import from CSV
swarma metric import hook-lab metrics.csv

# View logged metrics
swarma metric show hook-lab

copywriter,4.2,ctr_pct,week 1
copywriter,5.1,ctr_pct,week 2
researcher,7.8,relevance_score,

# Copy a template to your instance
cp -r "$(python -c "import swarma; print(swarma.__path__[0])")/examples/hook-lab" \
  ~/.swarma/instances/default/teams/hook-lab

# Or if you cloned the repo
cp -r examples/hook-lab ~/.swarma/instances/default/teams/hook-lab

# Run it
swarma cycle hook-lab --topic "why most startups fail"

swarma status

teams/my-squad/
├── team.yaml          # goal, flow, schedule, budget
├── program.md         # team context and constraints
└── agents/
    ├── researcher.yaml
    ├── writer.yaml
    └── strategy.md    # pre-seeded growth knowledge (evolves automatically)

name: my-squad
goal: find what works.
flow: "researcher -> writer"        # sequential
# flow: "researcher -> [writer, analyst]"  # parallel
schedule: "0 8 * * 1-5"            # optional: weekdays at 8am
budget: 30                          # optional: monthly budget in $

id: writer
name: Writer
instructions: |
  turn research into a post. max 200 words.
  hook in the first line. practitioner voice.
model: qwen/qwen3.5-plus-02-15     # optional: override default routing
metric:
  name: content_quality
  target: 8.0
experiment_config:
  min_sample_size: 5
  auto_propose: true

### Validated Patterns

**Specificity wins**
- Hooks with specific numbers outperform vague claims by 2-3x on saves
- "47% of startups" > "most startups"

### Anti-patterns (Discarded)
- Generic inspirational openings: -23% vs baseline. Discard.

### Patterns to Test
- [ ] First-person confession vs third-person case study
- [ ] Time-anchored ("In 2024...") vs timeless hooks

# Sequential: a runs, output passes to b
flow: "researcher -> writer"

# Parallel: a runs, then b and c run concurrently
flow: "researcher -> [writer, analyst]"

# Mixed: sequential then parallel then sequential
flow: "researcher -> [writer, analyst] -> judge"

# ~/.swarma/instances/default/config.yaml
knowledge:
  engine: qmd
  qmd_endpoint: http://localhost:8181/mcp

# 1. Run a cycle
swarma cycle starter --topic "test run"
# Expected: table showing agent outputs + costs

# 2. Check status
swarma status
# Expected: teams listed, recent run shown, costs displayed

# 3. Check a real squad (if installed)
swarma team show hook-lab
# Expected: team config with agents, flow, metrics

© glitch-rabin, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 422 other files in the repository root of glitch-rabin/swarma.

• SKILL.md
• .env.template
• .gitignore
• CONTRIBUTING.md
• LICENSE
• README.md
• brand/avatars/analyst.png
• brand/avatars/branded-test/analyst-hex-spit.png
• brand/avatars/branded-test/creator-bee.png
• brand/avatars/branded-test/hermes-badge.png
• brand/avatars/branded-test/mascot-bee.png
• brand/avatars/branded-test/mascot-hex-spit.png
• brand/avatars/branded-test/scanner-hex-spit.png
• brand/avatars/creator.png
• brand/avatars/hermes.png
• brand/avatars/scanner.png
• brand/avatars/strategist.png
• brand/avatars/swarma-mascot.png
• … and 405 more

Open the folder on GitHubat commit 4f62366