swarma

the growth experiment loop for AI agent swarms.

swarma.dev

English | 中文 | 日本語

---

your agents run tasks. swarma makes them run A/B tests instead.

describe what you want to improve. swarma generates the team, seeds it with real growth knowledge, runs experiments, scores results, issues verdicts, and evolves the strategy. after enough cycles, you have a validated playbook of what actually works.

strategy.md → execute → measure → verdict → updated strategy.md
     ↑                                              |
     └──────────────────────────────────────────────┘

applied learnings from QMD and the karpathy autoresearch pattern -- the same experiment loop that growth teams run, now applied to AI agent swarms.

why this exists

every growth team at Uber, Spotify, Facebook, Airbnb runs the same loop: hypothesize, test, measure, learn, repeat. the ones that win aren't smarter -- they just run more experiments and actually listen to the data. the playbook that emerges after thousands of cycles is the real asset.

the bottleneck was always human bandwidth. even the best teams max out at 2-5 experiments per week. AI agents remove that constraint. a swarm can run 50 experiments while a human team runs 2. but only if something is closing the loop.

that's what swarma does. the experiment infrastructure that growth teams at scale take for granted, packaged so any agent swarm can use it. same loop, same rigor, same compounding.

quickstart

pip install swarma

or from source:

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

swarma init                    # creates instance + starter team
swarma cycle starter           # run one cycle, see it work
swarma status                  # costs, runs, experiments

python 3.11+ and an openrouter API key. no GPU, no postgres, no docker. runs on a laptop or a $5 VPS.

generate a team from a goal

don't configure agents by hand. describe what you want and swarma builds the team.

swarma team create my-growth --from-goal "improve landing page conversion rate"

this calls an LLM to design a team with the right agents, flow, models, and a first experiment hypothesis. the generated team comes with:

• team.yaml -- goal, flow, budget
• agents/*.yaml -- individual agent configs with specific instructions
• program.md -- experiment patterns and constraints
• a first experiment ready to run

add business context for better results:

swarma team create growth-lab \
  --from-goal "optimize our signup funnel" \
  --context "B2B SaaS, 500 free users, 2% conversion to paid" \
  --budget 50

how the loop works

1. agent reads its strategy.md before every run
2. produces output (research, copy, analysis -- whatever the team does)
3. a cheap LLM scores the output against the agent's metric (1-10 scale, forced decimals)
4. score + reasoning logged to results.tsv
5. after min_sample_size cycles (default 3-5), verdict is issued automatically
6. strategy.md updated with what was learned
7. next cycle uses the evolved strategy

scoring: each output gets evaluated by a separate LLM call using the cheapest model in your routing table. the evaluator sees the output, the current strategy, the last 5 scores, and the metric definition. returns a precise score (7.3, not 7) plus reasoning and a strategy suggestion.

verdicts: after enough samples, swarma compares the experiment average against baseline. >20% improvement = keep (pattern validated, strategy updated). >20% decline = discard (reverted). in between = inconclusive (logged, try again with more data).

after a few experiments, your strategy.md evolves from seed knowledge into validated patterns:

## Validated (Exp 5)
contrarian opening + specific numbers in first line
> 23% improvement over baseline. keep this pattern.

## Inconclusive (Exp 2)
story-led hooks vs data-led hooks -- no significant difference (avg=8.1 vs baseline=7.9)
> next: increase sample size, results may be noise

feed real metrics back

LLM self-eval is a starting proxy. for production, feed back real-world signals:

# 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

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

# view logged metrics
swarma metric show hook-lab

CSV format: agent,value,metric_name,note

metrics auto-attach to the agent's active experiment. the experiment loop uses external metrics alongside LLM scores when both are available.

pre-seeded strategies

agents don't start from zero. each example squad includes a strategy.md seeded with real growth knowledge -- validated patterns, anti-patterns, and hypotheses to test. the experiment loop refines these over time.

example from the hook-lab strategy:

### Validated Patterns

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

**Loss framing > gain framing**
- "You're losing $X/month" outperforms "You could save $X/month" on CTR
- Exception: aspirational audiences respond better to gain framing

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

teams as config

a team is a folder. no code required.

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

# team.yaml
name: my-squad
goal: find what works.
flow: "researcher -> writer"
schedule: "0 8 * * 1-5"

# agents/writer.yaml
id: writer
name: Writer
instructions: |
  turn research into a post. max 200 words.
  hook in the first line. practitioner voice.
metric:
  name: content_quality
  target: 8.0
experiment_config:
  min_sample_size: 5
  auto_propose: true

models, tools, and expert lenses are configured in config.yaml. agents inherit defaults or override per-agent.

flow DSL supports sequential (a -> b), parallel (a -> [b, c, d]), and mixed pipelines.

18 example squads

ready-to-use squads in examples/, each with pre-seeded strategies:

cp -r examples/hook-lab ~/.swarma/instances/default/teams/
swarma cycle hook-lab

core growth squads:

squad	AARRR stage	what it tests
hook-lab	acquisition	opening lines -- what stops the scroll
landing-lab	acquisition	landing page copy and structure
seo-engine	acquisition	search presence and content ranking
cold-outbound	acquisition	outreach messaging and sequences
channel-mix	acquisition	multi-platform content strategy
activation-flow	activation	signup-to-value onboarding flows
pricing-lab	revenue	pricing presentation and packaging
retention-squad	retention	churn signals and win-back patterns
referral-engine	referral	viral loops and invite mechanics
competitive-intel	--	market monitoring and positioning

2026 growth ops squads:

squad	what it tests
ad-creative-lab	AI-generated ad creatives, multi-variant testing (50+ per campaign)
faceless-factory	faceless TikTok/Shorts at scale, retention curve optimization
ugc-factory	AI UGC-style content ($2-20/video vs $150-2K human)
programmatic-seo	template + data variable SEO pages at scale
newsletter-engine	newsletter growth, referral programs, ad placement
acquisition-squad	AI-powered outbound, intent signals, multi-channel sequences
community-engine	community-led growth, XP/quest gamification, ambassador programs
agentic-storefront	AI commerce optimization, dynamic pricing, conversational checkout

each includes a program.md with experiment patterns and a strategy.md with real growth knowledge as starting baseline.

integrations

hermes agent

swarma exposes an MCP server. connect it to hermes and your agent gets a dedicated experiment team that learns while it sleeps.

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

hermes stays clean -- sets direction, approves plans, asks "what did we learn?" swarma does the messy work.

claude code / claude desktop

{
  "mcpServers": {
    "swarma": {
      "command": "swarma",
      "args": ["serve", "--mcp"]
    }
  }
}

REST API

swarma serve --port 8282        # 30+ endpoints, OpenAPI docs at /docs

any MCP client

swarma serve --mcp              # stdio
swarma serve --mcp --mcp-port 8383   # HTTP

note: when running as MCP subprocess, pass OPENROUTER_API_KEY in your MCP config's env block -- the instance .env is not inherited by subprocesses.

knowledge layer (QMD)

agents learn individually via strategy.md. to learn across teams, add QMD -- a search engine that indexes all agent outputs. BM25 + vector + rerank. no GPU required.

pip install qmd
qmd init
qmd serve                          # http://localhost:8181

# config.yaml
knowledge:
  engine: qmd
  qmd_endpoint: http://localhost:8181/mcp

every agent output gets indexed automatically. agents search what other agents learned. the experiment loop gets shared memory.

when an experiment gets a keep verdict, the validated pattern is automatically saved to a cross-team playbook collection. every agent sees patterns from every other team in their context window. anti-patterns (discarded experiments) are tracked too, so teams avoid repeating failed approaches.

# semantic search across all validated patterns
curl localhost:8282/playbook/search?q=hook+specificity

what swarma is not

• not memory -- honcho does memory. swarma does learning loops.
• not automation -- n8n/make do workflows. swarma runs experiments.
• not a prompt library -- agency-agents has 135 templates. swarma teaches them what works through feedback loops.
• not orchestration -- crewai/autogen run pipelines. swarma adds the feedback loop that makes pipelines improve.

the difference: a prompt template tells an agent what to do once. swarma teaches it what works over time. templates are the starting point. the playbook is the output.

roadmap

• experiment loop (strategy -> execute -> measure -> verdict)
• expert reasoning lenses (34 composable thinking frameworks)
• dashboard UI (experiment viewer, playbook, strategy evolution)
• team generator (swarma team create --from-goal)
• external metric ingestion (swarma metric log/import/show)
• pre-seeded strategy files with real growth knowledge
• pip install swarma on PyPI
• QMD cross-team wiring (verdict -> playbook -> shared knowledge)
• 18 example squads covering full AARRR funnel + 2026 growth ops
• anti-pattern tracking (discard verdicts saved to playbook)
• /playbook/search semantic search across teams via QMD
• webhook metric ingestion (real-time analytics callbacks)
• hermes skills hub + openclaw marketplace publishing
• squad marketplace (share and discover validated teams)
• HuggingFace dataset seeding for squad knowledge

contributing

swarma is early. if you're interested in experiment loops for agents, open an issue or PR.

license

MIT