Skip to content
Back to search

swarma

SkillWorks with Claude CodeGitHub

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/glitch-rabin--swarma/badge.svg)](/listings/glitch-rabin--swarma)

HTML

<a href="/listings/glitch-rabin--swarma"><img src="/api/listings/glitch-rabin--swarma/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install swarma
swarma init
swarma cycle starter --topic "why do startups fail?"

three commands. python 3.11+ and an [OpenRouter](https://openrouter.ai/) API key. no GPU, no postgres, no docker.

or from source:

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

MCP integration (Claude Code / Claude Desktop)

after installing, add to your MCP config (`.mcp.json`):

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 545 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: swarma
  3. 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."
  4. version: 0.2.0
  5. license: MIT
  6. compatibility: Python 3.11+, pip, terminal access
  7. metadata:
  8. repository: https://github.com/glitch-rabin/swarma
  9. website: https://swarma.dev
  10. hook: "a swarm runs 50 experiments while a human team runs 2"
  11. keywords: [growth experiments, A/B testing, agent teams, swarm intelligence, AARRR funnel, playbook, learning agents, experiment loop, strategy evolution, self-improving]
  12. hermes:
  13. tags: [experiments, learning, growth, agents, teams, swarms, pirate-funnels, AARRR, playbook, self-improving, A/B-testing]
  14. category: productivity
  15. requires_toolsets: [terminal]
  16. required_environment_variables:
  17. - name: OPENROUTER_API_KEY
  18. prompt: "OpenRouter API key for LLM calls"
  19. help: https://openrouter.ai/keys
  20. required_for: running agent cycles
  21. ---
  22. # swarma -- growth experiment loop for agent teams
  23. ## When to Use This Skill
  24. Use swarma when the user wants to:
  25. - Run growth experiments (hooks, landing pages, outreach, pricing, activation, retention)
  26. - Build agent teams that **learn and improve** through A/B testing, not just execute once
  27. - Get a validated playbook of what actually works for their specific audience/product
  28. - Test ideas at scale (50+ experiments/week instead of 2-5)
  29. - Replace "we tried that, it didn't work" with logged, analyzed, searchable experiment data
  30. **Trigger phrases**: "test what works", "optimize my funnel", "find the best hooks", "run experiments", "A/B test", "what's working", "build a playbook", "growth experiments", "improve conversion"
  31. **Do NOT use when**: user wants workflow automation (use n8n/Make), conversation memory (use honcho), or one-shot agent pipelines (use CrewAI/AutoGen). swarma is specifically for experiment loops that improve over time.
  32. ---
  33. ## Quick Reference
  34. ### Commands at a Glance
  35. | Command | What it does | When to use |
  36. |---------|-------------|-------------|
  37. | `swarma init` | Create instance + starter team | First-time setup |
  38. | `swarma cycle <team>` | Run one experiment cycle | Testing, manual runs |
  39. | `swarma cycle <team> --topic "..."` | Run cycle with a specific topic | Ad-hoc experiments |
  40. | `swarma team create <name> --from-goal "..."` | Generate team from a goal | Starting a new experiment area |
  41. | `swarma team show <name>` | Inspect a team's config | Reviewing what was generated |
  42. | `swarma team list` | Show all teams | Overview |
  43. | `swarma status` | Costs, recent runs, experiments | Health check |
  44. | `swarma metric log <team> <agent> <value>` | Log external metric | Feeding real-world data |
  45. | `swarma metric import <team> <csv>` | Bulk import metrics | Batch data ingestion |
  46. | `swarma metric show <team>` | View logged metrics | Reviewing performance |
  47. | `swarma serve --port 8282` | Start REST API | External integrations |
  48. | `swarma serve --mcp` | Start MCP server | Claude Code / Hermes integration |
  49. | `swarma run` | Start scheduled engine | Continuous operation |
  50. | `swarma expert list` | Browse reasoning lenses | Exploring expert frameworks |
  51. ### Decision: Which Squad Template?
  52. | User wants to improve... | Use this squad | AARRR stage |
  53. |--------------------------|---------------|-------------|
  54. | Opening lines / hooks | `hook-lab` | Acquisition |
  55. | Landing page copy | `landing-lab` | Acquisition |
  56. | SEO rankings | `seo-engine` | Acquisition |
  57. | Cold outreach response rates | `cold-outbound` | Acquisition |
  58. | Multi-platform content | `channel-mix` | Acquisition |
  59. | Signup-to-value onboarding | `activation-flow` | Activation |
  60. | Pricing and packaging | `pricing-lab` | Revenue |
  61. | Churn and retention | `retention-squad` | Retention |
  62. | Viral loops and referrals | `referral-engine` | Referral |
  63. | Market positioning | `competitive-intel` | -- |
  64. | Short-form video pipeline | `faceless-factory` | Acquisition |
  65. | Ad creative testing | `ad-creative-lab` | Acquisition |
  66. | UGC content simulation | `ugc-factory` | Acquisition |
  67. | Programmatic SEO | `programmatic-seo` | Acquisition |
  68. | Newsletter growth | `newsletter-engine` | Retention |
  69. | Paid + organic loops | `acquisition-squad` | Acquisition |
  70. | Community-led growth | `community-engine` | Retention |
  71. | AI commerce optimization | `agentic-storefront` | Revenue |
  72. ### Decision: Generate vs Template?
  73. | Situation | Approach |
  74. |-----------|----------|
  75. | User has a specific, well-defined goal | `swarma team create --from-goal` (let AI design the team) |
  76. | Goal matches an existing squad template | Copy template, then customize |
  77. | User wants to experiment broadly | Start with `hook-lab` (most general) |
  78. | User doesn't know where to start | Ask about their funnel bottleneck, then pick |
  79. ---
  80. ## The GROWS Loop (Core Concept)
  81. Every experiment cycle follows five steps:
  82. ```
  83. Generate Run Observe Weigh Stack
  84. hypothesis --> experiment --> signal --> verdict --> playbook
  85. ^ |
  86. └──────────────────────────────────────────────────┘
  87. ```
  88. | Step | What happens | Where in code |
  89. |------|-------------|---------------|
  90. | **G -- Generate** | Agent reads `strategy.md`, proposes a hypothesis | `core/cycle.py` |
  91. | **R -- Run** | Agent executes with hypothesis active, produces output | `flow/executor.py` |
  92. | **O -- Observe** | Separate cheap LLM scores output (1-10, forced decimals) | `core/agent.py` |
  93. | **W -- Weigh** | After 5 cycles, compare average vs baseline. >20% = keep/discard | `core/experiment.py` |
  94. | **S -- Stack** | Validated patterns written to `strategy.md` + playbook | `core/agent.py` |
  95. **Key numbers:**
  96. - Verdict threshold: 20% improvement to keep, 20% decline to discard
  97. - Default `min_sample_size`: 5 cycles before verdict
  98. - Scoring: 1-10 scale with forced decimals (7.3, not 7)
  99. ---
  100. ## Setup Guide
  101. ### Platform: Claude Code / Claude Desktop
  102. ```bash
  103. pip install swarma
  104. swarma init
  105. ```
  106. Add to `.mcp.json`:
  107. ```json
  108. {
  109. "mcpServers": {
  110. "swarma": {
  111. "command": "swarma",
  112. "args": ["serve", "--mcp"],
  113. "env": { "OPENROUTER_API_KEY": "sk-or-..." }
  114. }
  115. }
  116. }
  117. ```
  118. **Important**: `OPENROUTER_API_KEY` must be in the MCP `env` block. The instance `.env` is not inherited by subprocesses.
  119. ### Platform: Hermes (via terminal)
  120. Hermes has terminal access -- it can run swarma CLI commands directly. No MCP required.
  121. ```bash
  122. pip install swarma
  123. swarma init
  124. ```
  125. Then tell Hermes: *"run `swarma cycle hook-lab --topic 'AI agents are overhyped'`"*
  126. Hermes reads terminal output and acts on results. For structured access, add MCP:
  127. ```yaml
  128. # hermes config.yaml
  129. mcp_servers:
  130. swarma:
  131. transport: stdio
  132. command: swarma
  133. args: ["serve", "--mcp"]
  134. env:
  135. OPENROUTER_API_KEY: "sk-or-..."
  136. ```
  137. ### Platform: OpenClaw
  138. ```bash
  139. pip install swarma
  140. swarma init
  141. ```
  142. Configure as MCP tool or use terminal access depending on your OpenClaw setup.
  143. ### Platform: CLI (standalone)
  144. ```bash
  145. pip install swarma
  146. swarma init # creates instance + starter team
  147. swarma cycle starter --topic "why do startups fail?" # run one cycle
  148. swarma status # check costs, runs, experiments
  149. ```
  150. ### From source
  151. ```bash
  152. git clone https://github.com/glitch-rabin/swarma.git
  153. cd swarma && pip install -e .
  154. swarma init
  155. ```
  156. ### Environment setup
  157. After `swarma init`, add your API key:
  158. ```bash
  159. echo "OPENROUTER_API_KEY=sk-or-..." >> ~/.swarma/instances/default/.env
  160. ```
  161. Get a key at [openrouter.ai/keys](https://openrouter.ai/keys).
  162. Optional (for cross-team knowledge):
  163. ```bash
  164. # Only needed when running 3+ teams
  165. echo "QMD_ENDPOINT=http://localhost:8181/mcp" >> ~/.swarma/instances/default/.env
  166. ```
  167. ---
  168. ## Onboarding Flow
  169. When a user wants to set up swarma, follow this sequence. The team generator is the fastest path -- don't make users configure agents manually.
  170. ### Step 1: Understand the goal
  171. Ask:
  172. - "What do you want to improve?" (conversion, engagement, outreach response rate, SEO rankings, etc.)
  173. - "Who is your audience?" (B2B SaaS users, crypto community, enterprise buyers, etc.)
  174. - "What does success look like?" (more signups, higher CTR, better reply rates, etc.)
  175. ### Step 2: Install
  176. ```bash
  177. pip install swarma
  178. swarma init --yes
  179. ```
  180. ### Step 3: Generate the team
  181. This is the key step. Use the team generator instead of picking templates.
  182. ```bash
  183. swarma team create growth-lab \
  184. --from-goal "optimize landing page conversion for our B2B SaaS" \
  185. --context "developer tools company, 500 free users, 2% conversion to paid" \
  186. --budget 30
  187. ```
  188. The generator:
  189. 1. Designs the team (2-5 agents with specific roles)
  190. 2. Picks models that fit each role
  191. 3. Writes agent instructions and experiment patterns
  192. 4. Creates a first experiment hypothesis ready to run
  193. Review what it generated:
  194. ```bash
  195. swarma team show growth-lab
  196. ```
  197. ### Step 4: Run the first cycle
  198. ```bash
  199. swarma cycle growth-lab
  200. ```
  201. Expected output:
  202. ```
  203. Running cycle: growth-lab
  204. flow: researcher -> copywriter -> judge
  205. agents: ['researcher', 'copywriter', 'judge']
  206. Cycle: growth-lab
  207. Agent Model Cost Output Preview
  208. researcher sonar-pro $0.000384 **Topic:** 52% of executives...
  209. copywriter qwen3.5-plus-02-15 $0.000746 [A] We sent 4,382 cold emails...
  210. judge mistral-nemo $0.000416 **Hook Variations:** A: "Did...
  211. duration: 43.9s | total cost: $0.001546 | agents: 3
  212. ```
  213. ### Step 5: Run more cycles and review
  214. ```bash
  215. swarma cycle growth-lab # run another cycle
  216. swarma cycle growth-lab --topic "specific angle" # with a topic
  217. swarma status # check progress
  218. ```
  219. After 5 cycles, the experiment engine issues its first verdict. The strategy file evolves automatically.
  220. ---
  221. ## Day-to-Day Usage
  222. ### Running experiments
  223. ```bash
  224. # Single cycle
  225. swarma cycle hook-lab
  226. # With a specific topic
  227. swarma cycle hook-lab --topic "AI agents are commoditizing"
  228. # Continuous (teams with cron schedules run automatically)
  229. swarma run
  230. # Continuous with API server
  231. swarma run --port 8282
  232. ```
  233. ### Feeding real metrics
  234. LLM self-eval is a starting proxy. For production, feed back real-world signals:
  235. ```bash
  236. # Log a single metric
  237. swarma metric log hook-lab copywriter 4.2 --metric ctr_pct
  238. # Attach to a specific experiment
  239. swarma metric log hook-lab copywriter 127 --metric impressions --exp 3
  240. # Add a note
  241. swarma metric log hook-lab copywriter 5.1 --metric ctr_pct --note "from linkedin analytics"
  242. # Bulk import from CSV
  243. swarma metric import hook-lab metrics.csv
  244. # View logged metrics
  245. swarma metric show hook-lab
  246. ```
  247. CSV format: `agent,value,metric_name,note`
  248. ```csv
  249. copywriter,4.2,ctr_pct,week 1
  250. copywriter,5.1,ctr_pct,week 2
  251. researcher,7.8,relevance_score,
  252. ```
  253. ### Using squad templates
  254. ```bash
  255. # Copy a template to your instance
  256. cp -r "$(python -c "import swarma; print(swarma.__path__[0])")/examples/hook-lab" \
  257. ~/.swarma/instances/default/teams/hook-lab
  258. # Or if you cloned the repo
  259. cp -r examples/hook-lab ~/.swarma/instances/default/teams/hook-lab
  260. # Run it
  261. swarma cycle hook-lab --topic "why most startups fail"
  262. ```
  263. ### Checking status
  264. ```bash
  265. swarma status
  266. ```
  267. Shows: all teams, recent runs, costs (today + this month), pending plans, queue stats.
  268. ---
  269. ## MCP Tools Reference
  270. When connected via MCP, these 16 tools are available:
  271. | Tool | Description | Parameters |
  272. |------|-------------|------------|
  273. | `swarma_health` | Check if swarma is running | -- |
  274. | `swarma_list_teams` | List all configured teams | -- |
  275. | `swarma_get_team` | Get team details (agents, flow, schedule) | `team_id` |
  276. | `swarma_list_agents` | List agents in a team | `team_id` |
  277. | `swarma_run_agent` | Run a single agent with optional context | `team_id`, `agent_id`, `context?` |
  278. | `swarma_run_cycle` | Run a full cycle for a team | `team_id`, `topic?` |
  279. | `swarma_status` | Instance status (costs, runs, experiments) | -- |
  280. | `swarma_costs` | Cost breakdown (today, this month) | -- |
  281. | `swarma_list_plans` | Show pending experiment plans | `team_id?` |
  282. | `swarma_approve_plan` | Approve a pending experiment plan | `plan_id` |
  283. | `swarma_reject_plan` | Reject a pending plan | `plan_id`, `reason?` |
  284. | `swarma_get_outputs` | Recent outputs from agents | `team_id?`, `agent_id?`, `limit?` |
  285. | `swarma_list_tools` | List available agent tools | -- |
  286. | `swarma_list_experts` | Browse expert reasoning lenses | -- |
  287. | `swarma_get_expert` | Get expert details by ID | `expert_id` |
  288. | `swarma_generate_team` | Generate a new team from a goal | `name`, `goal`, `context?`, `budget?` |
  289. ### Common MCP Workflows
  290. **"What's been happening?"**
  291. 1. `swarma_status` -- overview
  292. 2. `swarma_get_outputs` -- recent agent outputs
  293. 3. `swarma_list_plans` -- pending experiments
  294. **"Run an experiment"**
  295. 1. `swarma_run_cycle` with team_id and optional topic
  296. 2. `swarma_get_outputs` to review results
  297. **"Start a new experiment area"**
  298. 1. `swarma_generate_team` with goal and context
  299. 2. `swarma_get_team` to review what was generated
  300. 3. `swarma_run_cycle` to kick it off
  301. **"What's working?"**
  302. 1. `swarma_get_outputs` for recent results
  303. 2. Read the team's `strategy.md` for validated patterns
  304. ---
  305. ## Team Configuration Reference
  306. A team is a folder. No code required.
  307. ```
  308. teams/my-squad/
  309. ├── team.yaml # goal, flow, schedule, budget
  310. ├── program.md # team context and constraints
  311. └── agents/
  312. ├── researcher.yaml
  313. ├── writer.yaml
  314. └── strategy.md # pre-seeded growth knowledge (evolves automatically)
  315. ```
  316. ### team.yaml
  317. ```yaml
  318. name: my-squad
  319. goal: find what works.
  320. flow: "researcher -> writer" # sequential
  321. # flow: "researcher -> [writer, analyst]" # parallel
  322. schedule: "0 8 * * 1-5" # optional: weekdays at 8am
  323. budget: 30 # optional: monthly budget in $
  324. ```
  325. ### agent.yaml
  326. ```yaml
  327. id: writer
  328. name: Writer
  329. instructions: |
  330. turn research into a post. max 200 words.
  331. hook in the first line. practitioner voice.
  332. model: qwen/qwen3.5-plus-02-15 # optional: override default routing
  333. metric:
  334. name: content_quality
  335. target: 8.0
  336. experiment_config:
  337. min_sample_size: 5
  338. auto_propose: true
  339. ```
  340. ### strategy.md (evolves automatically)
  341. Starts with seed knowledge, grows with every validated experiment:
  342. ```markdown
  343. ### Validated Patterns
  344. **Specificity wins**
  345. - Hooks with specific numbers outperform vague claims by 2-3x on saves
  346. - "47% of startups" > "most startups"
  347. ### Anti-patterns (Discarded)
  348. - Generic inspirational openings: -23% vs baseline. Discard.
  349. ### Patterns to Test
  350. - [ ] First-person confession vs third-person case study
  351. - [ ] Time-anchored ("In 2024...") vs timeless hooks
  352. ```
  353. ### Flow DSL
  354. ```yaml
  355. # Sequential: a runs, output passes to b
  356. flow: "researcher -> writer"
  357. # Parallel: a runs, then b and c run concurrently
  358. flow: "researcher -> [writer, analyst]"
  359. # Mixed: sequential then parallel then sequential
  360. flow: "researcher -> [writer, analyst] -> judge"
  361. ```
  362. ---
  363. ## Cross-Team Knowledge (QMD)
  364. By default, each team learns individually via its own `strategy.md`. To share knowledge across teams, wire in QMD:
  365. ```yaml
  366. # ~/.swarma/instances/default/config.yaml
  367. knowledge:
  368. engine: qmd
  369. qmd_endpoint: http://localhost:8181/mcp
  370. ```
  371. With QMD: team A discovers loss framing beats gain framing, team B sees that pattern in its next cycle. Anti-patterns are shared too.
  372. **You don't need QMD** until running 3+ teams. Most users start without it.
  373. ---
  374. ## Troubleshooting
  375. | Problem | Cause | Fix |
  376. |---------|-------|-----|
  377. | "No API key found" | Missing `OPENROUTER_API_KEY` | Add to `~/.swarma/instances/default/.env` |
  378. | MCP subprocess can't find key | Instance `.env` not inherited | Pass key in MCP config `env` block |
  379. | "No teams found" | Empty instance | Run `swarma init` or copy a squad template |
  380. | Experiments not issuing verdicts | Not enough cycles | Need `min_sample_size` (default 5) completed cycles |
  381. | Strategy file not evolving | No verdict yet | Run more cycles, check `swarma status` |
  382. | `swarma cycle` shows $0.000000 cost | Model returned empty | Check API key validity, try `swarma cycle starter` |
  383. | QMD not connecting | QMD not running | Start with `qmd serve` before swarma |
  384. | Results.tsv empty | No cycles completed | Run at least one cycle first |
  385. ---
  386. ## Verification
  387. After setup, verify everything works:
  388. ```bash
  389. # 1. Run a cycle
  390. swarma cycle starter --topic "test run"
  391. # Expected: table showing agent outputs + costs
  392. # 2. Check status
  393. swarma status
  394. # Expected: teams listed, recent run shown, costs displayed
  395. # 3. Check a real squad (if installed)
  396. swarma team show hook-lab
  397. # Expected: team config with agents, flow, metrics
  398. ```
  399. If all three pass, the GROWS loop is operational.
  400. ---
  401. ## What swarma Is Not
  402. | swarma is not... | Use this instead | The difference |
  403. |-------------------|-----------------|----------------|
  404. | **memory** | honcho | swarma doesn't remember conversations. it runs experiment loops. |
  405. | **workflow automation** | n8n, Make, Zapier | those connect apps. swarma runs hypotheses and learns from results. |
  406. | **a prompt library** | agency-agents | swarma teaches agents what works through feedback. templates go in, playbooks come out. |
  407. | **agent orchestration** | CrewAI, AutoGen, LangGraph | those run pipelines. swarma adds the GROWS loop that makes pipelines improve. |
  408. | **a hosted service** | -- | self-hosted. your data stays on your machine. |
README.md · README · 387 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # swarma
  2. growth loops, automated.
  3. **[swarma.dev](https://swarma.dev)**
  4. ---
  5. <p align="center">
  6. <img src="brand/scenes/v2/05-van-studio.png" alt="swarma — growth loops, automated" width="100%">
  7. </p>
  8. <p align="center">
  9. <img src="https://img.shields.io/badge/version-0.2.0-blue" alt="Version">
  10. <img src="https://img.shields.io/badge/python-3.11+-green" alt="Python">
  11. <img src="https://img.shields.io/badge/license-MIT-yellow" alt="License">
  12. <img src="https://img.shields.io/pypi/v/swarma" alt="PyPI">
  13. </p>
  14. an agent without a team is just a prompt with no context. nobody hires a writer with no research team, no analytics, no strategy, no feedback loop.
  15. swarma builds agent **teams** that run growth experiments, score results, issue verdicts, and evolve their own strategy. after enough cycles, you have a validated playbook of what actually works. self-hosted. runs on a laptop or a VPS.
  16. one folder = one team. one cycle = one experiment. the playbook writes itself.
  17. ## swarma is right for you if
  18. - you run growth experiments (hooks, landing pages, outreach, pricing, activation) and want to run 50x more of them
  19. - you want agent teams that **learn and improve** through A/B testing, not just execute once
  20. - you want a validated playbook of what works for your specific audience, not generic advice
  21. - you care about self-hosted, no vendor lock-in, and owning your data
  22. - you want swarms that get smarter every cycle, not pipelines that run once and forget
  23. ## quickstart
  24. ```bash
  25. pip install swarma
  26. swarma init
  27. swarma cycle starter --topic "why do startups fail?"
  28. ```
  29. three commands. python 3.11+ and an [OpenRouter](https://openrouter.ai/) API key. no GPU, no postgres, no docker.
  30. or from source:
  31. ```bash
  32. git clone https://github.com/glitch-rabin/swarma.git
  33. cd swarma && pip install -e .
  34. ```
  35. ### MCP integration (Claude Code / Claude Desktop)
  36. after installing, add to your MCP config (`.mcp.json`):
  37. ```json
  38. {
  39. "mcpServers": {
  40. "swarma": {
  41. "command": "swarma",
  42. "args": ["serve", "--mcp"],
  43. "env": { "OPENROUTER_API_KEY": "sk-or-..." }
  44. }
  45. }
  46. }
  47. ```
  48. ## the GROWS loop
  49. every cycle follows GROWS -- five steps, no exceptions:
  50. ```
  51. Generate Run Observe Weigh Stack
  52. hypothesis --> experiment --> signal --> verdict --> playbook
  53. ^ |
  54. └──────────────────────────────────────────────────┘
  55. ```
  56. | Step | What happens |
  57. |------|-------------|
  58. | **G -- Generate** | Agent reads its `strategy.md`, proposes a hypothesis. "contrarian opening lines will outperform data-led hooks on saves." |
  59. | **R -- Run** | Agent executes with the hypothesis active. Produces output -- research, copy, analysis, whatever the team does. |
  60. | **O -- Observe** | A separate LLM scores the output against the agent's target metric (1-10 scale, forced decimals). Score + reasoning logged to `results.tsv`. |
  61. | **W -- Weigh** | After `min_sample_size` cycles (default 5), swarma compares experiment average against baseline. >20% up = **keep**. >20% down = **discard**. In between = **inconclusive**. |
  62. | **S -- Stack** | Validated patterns get written back to `strategy.md` and pushed to the shared playbook. Next cycle generates a new hypothesis from the evolved strategy. |
  63. this is the same loop every growth team at Uber, Spotify, and Airbnb runs. swarma removes the human bandwidth bottleneck. a swarm runs 50 experiments while a human team runs 2.
  64. ## without swarma vs with swarma
  65. | | Without | With swarma |
  66. |---|---------|------------|
  67. | **Experiments per week** | 2-5 (limited by human bandwidth) | 50+ (limited by API budget) |
  68. | **Knowledge sharing** | Lives in Slack threads, dies there | Every result logged to `results.tsv`, strategies evolve per team |
  69. | **Strategy evolution** | Manual review meetings, quarterly | Automatic after every experiment cycle |
  70. | **Learning from failure** | "We tried that, it didn't work" (no record) | Logged, analyzed, anti-patterns tracked |
  71. | **Cross-team learning** | Team A doesn't know what Team B learned | Optional shared playbook via QMD (cross-team knowledge) |
  72. | **Starting point** | Blank page or generic templates | Pre-seeded strategies from real growth knowledge |
  73. ## generate a team from a goal
  74. don't configure agents by hand. describe what you want and swarma builds the team.
  75. ```bash
  76. swarma team create my-growth --from-goal "improve landing page conversion rate"
  77. ```
  78. this calls an LLM to design a team with the right agents, flow, models, and a first experiment hypothesis. the generated team comes with:
  79. - `team.yaml` -- goal, flow, budget
  80. - `agents/*.yaml` -- individual agent configs with specific instructions
  81. - `program.md` -- experiment patterns and constraints
  82. - a first experiment ready to run
  83. add business context for better results:
  84. ```bash
  85. swarma team create growth-lab \
  86. --from-goal "optimize our signup funnel" \
  87. --context "B2B SaaS, 500 free users, 2% conversion to paid" \
  88. --budget 50
  89. ```
  90. ## teams as config
  91. a team is a folder. no code required.
  92. ```
  93. teams/my-squad/
  94. ├── team.yaml # goal, flow, schedule, budget
  95. ├── program.md # team context and constraints
  96. └── agents/
  97. ├── researcher.yaml
  98. ├── writer.yaml
  99. └── strategy.md # pre-seeded growth knowledge (evolves automatically)
  100. ```
  101. ```yaml
  102. # team.yaml
  103. name: my-squad
  104. goal: find what works.
  105. flow: "researcher -> writer"
  106. schedule: "0 8 * * 1-5"
  107. ```
  108. ```yaml
  109. # agents/writer.yaml
  110. id: writer
  111. name: Writer
  112. instructions: |
  113. turn research into a post. max 200 words.
  114. hook in the first line. practitioner voice.
  115. metric:
  116. name: content_quality
  117. target: 8.0
  118. experiment_config:
  119. min_sample_size: 5
  120. auto_propose: true
  121. ```
  122. models are configured per-agent in their YAML files. `swarma init` creates a `config.yaml` at `~/.swarma/instances/default/` with model routing defaults.
  123. flow DSL supports sequential (`a -> b`), parallel (`a -> [b, c, d]`), and mixed pipelines.
  124. ## how the loop works (detailed)
  125. 1. agent reads its `strategy.md` before every run
  126. 2. produces output (research, copy, analysis -- whatever the team does)
  127. 3. a cheap LLM scores the output against the agent's metric (1-10 scale, forced decimals)
  128. 4. score + reasoning logged to `results.tsv`
  129. 5. after `min_sample_size` cycles (default 5), verdict is issued automatically
  130. 6. `strategy.md` updated with what was learned
  131. 7. next cycle uses the evolved strategy
  132. **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.
  133. **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).
  134. after a few experiments, your `strategy.md` evolves from seed knowledge into validated patterns:
  135. ```markdown
  136. ## Validated (Exp 5)
  137. contrarian opening + specific numbers in first line
  138. > 23% improvement over baseline. keep this pattern.
  139. ## Inconclusive (Exp 2)
  140. story-led hooks vs data-led hooks -- no significant difference (avg=8.1 vs baseline=7.9)
  141. > next: increase sample size, results may be noise
  142. ```
  143. ## feed real metrics back
  144. LLM self-eval is a starting proxy. for production, feed back real-world signals:
  145. ```bash
  146. # log a single metric
  147. swarma metric log hook-lab copywriter 4.2 --metric ctr_pct
  148. # attach to a specific experiment
  149. swarma metric log hook-lab copywriter 127 --metric impressions --exp 3
  150. # bulk import from CSV
  151. swarma metric import hook-lab metrics.csv
  152. # view logged metrics
  153. swarma metric show hook-lab
  154. ```
  155. CSV format: `agent,value,metric_name,note`
  156. metrics auto-attach to the agent's active experiment. the experiment loop uses external metrics alongside LLM scores when both are available.
  157. ## pre-seeded strategies
  158. agents don't start from zero. each squad includes a `strategy.md` seeded with real growth knowledge -- validated patterns, anti-patterns, and hypotheses to test. the GROWS loop refines these over time.
  159. example from the hook-lab strategy:
  160. ```markdown
  161. ### Validated Patterns
  162. **Specificity wins**
  163. - Hooks with specific numbers outperform vague claims by 2-3x on saves
  164. - "47% of startups" > "most startups"
  165. **Loss framing > gain framing**
  166. - "You're losing $X/month" outperforms "You could save $X/month" on CTR
  167. - Exception: aspirational audiences respond better to gain framing
  168. ### Patterns to Test
  169. - [ ] First-person confession vs third-person case study
  170. - [ ] Time-anchored ("In 2024...") vs timeless hooks
  171. ```
  172. ## 18 squad templates
  173. ready-to-use squads in [`examples/`](examples/), each with pre-seeded strategies:
  174. ```bash
  175. cp -r examples/hook-lab ~/.swarma/instances/default/teams/
  176. swarma cycle hook-lab
  177. ```
  178. **core growth squads:**
  179. | squad | AARRR stage | what it tests | agents |
  180. |-------|------------|--------------|--------|
  181. | `hook-lab` | acquisition | opening lines -- what stops the scroll | 3 |
  182. | `landing-lab` | acquisition | landing page copy and structure | 3 |
  183. | `seo-engine` | acquisition | search presence and content ranking | 3 |
  184. | `cold-outbound` | acquisition | outreach messaging and sequences | 3 |
  185. | `channel-mix` | acquisition | multi-platform content strategy | 3 |
  186. | `activation-flow` | activation | signup-to-value onboarding flows | 3 |
  187. | `pricing-lab` | revenue | pricing presentation and packaging | 3 |
  188. | `retention-squad` | retention | churn signals and win-back patterns | 3 |
  189. | `referral-engine` | referral | viral loops and invite mechanics | 3 |
  190. | `competitive-intel` | -- | market monitoring and positioning | 3 |
  191. **2026 growth ops squads:**
  192. | squad | what it tests | agents |
  193. |-------|--------------|--------|
  194. | `faceless-factory` | automated short-form video pipeline | 3 |
  195. | `ad-creative-lab` | performance creative testing at scale | 3 |
  196. | `ugc-factory` | user-generated content simulation | 3 |
  197. | `programmatic-seo` | automated SEO content at scale | 3 |
  198. | `newsletter-engine` | newsletter growth + retention | 3 |
  199. | `acquisition-squad` | paid + organic acquisition loops | 3 |
  200. | `community-engine` | community-led growth automation | 3 |
  201. | `agentic-storefront` | AI-powered commerce optimization | 3 |
  202. each includes a `program.md` with experiment patterns and a `strategy.md` with real growth knowledge as starting baseline.
  203. ## what swarma is not
  204. | swarma is not... | Use this instead | The difference |
  205. |-------------------|-----------------|----------------|
  206. | **memory** | [honcho](https://github.com/plastic-labs/honcho) | swarma doesn't remember conversations. it runs experiment loops and builds playbooks. |
  207. | **workflow automation** | n8n, Make, Zapier | those connect apps. swarma runs hypotheses through agent teams and learns from results. |
  208. | **a prompt library** | [agency-agents](https://github.com/msitarzewski/agency-agents) (135 templates) | templates are a starting point. swarma teaches agents what works through feedback loops. templates go in, playbooks come out. |
  209. | **agent orchestration** | CrewAI, AutoGen, LangGraph | those run pipelines. swarma adds the GROWS loop that makes pipelines *improve*. orchestration is step 1. learning is the whole game. |
  210. | **a hosted service** | -- | swarma is self-hosted. your data stays on your machine. no accounts, no telemetry, no vendor lock-in. |
  211. ## works with
  212. swarma is the engine. connect it to an operator for the full experience.
  213. ### Hermes
  214. [Hermes](https://github.com/nousresearch/hermes-agent) by NousResearch is the operator layer swarma is designed for. Hermes has terminal access -- it can run `swarma cycle`, `swarma team create`, and read results directly. no MCP required.
  215. swarma is the machine. Hermes is the executive. together they're the system from [the original article](https://x.com/glitch_).
  216. ### QMD cross-team knowledge
  217. by default, each team learns individually via its own `strategy.md`. to learn **across** teams, wire in [QMD](https://github.com/tobi/qmd) -- a local knowledge engine by Tobi Lutke. BM25 + vector + rerank. runs on your machine, no GPU.
  218. ```yaml
  219. # config.yaml
  220. knowledge:
  221. engine: qmd
  222. qmd_endpoint: http://localhost:8181/mcp
  223. ```
  224. with QMD: team A discovers loss framing beats gain framing, team B sees that pattern in its next cycle. without QMD: teams still learn individually. most users don't need this until running 3+ teams.
  225. ### REST API
  226. ```bash
  227. swarma serve --port 8282 # 30+ endpoints, OpenAPI docs at /docs
  228. ```
  229. ## FAQ
  230. **do I need Hermes to use swarma?**
  231. no. swarma works standalone via CLI. Hermes adds the operator layer -- Telegram/Slack control, approval flows, scheduled cycles. it's how you get the full experience, but swarma runs experiments on its own.
  232. **do I need QMD?**
  233. no. QMD adds cross-team knowledge sharing. without it, each team learns individually via its own `strategy.md`. add QMD when you're running multiple teams and want them to learn from each other.
  234. **what models does it use?**
  235. any model on [OpenRouter](https://openrouter.ai/). swarma uses a routing table that maps task types (generation, evaluation, routing) to models. you configure this in the instance `config.yaml` created by `swarma init`, and can override per-agent.
  236. **is this like CrewAI / AutoGen / LangGraph?**
  237. those are orchestration frameworks -- they run agent pipelines. swarma adds the experiment loop on top. orchestration is "agent A passes output to agent B." swarma is "agent A passes output to agent B, the output gets scored, and the strategy evolves based on what works." the GROWS loop is the difference.
  238. **can I use this for things other than growth marketing?**
  239. the engine doesn't care what the team does. it cares about agents, metrics, and experiments. if you can define a north star metric, swarma can run experiments toward it.
  240. **is my data sent anywhere?**
  241. your prompts and outputs go to OpenRouter (which routes to the model provider). everything else -- strategies, experiment logs, playbooks, knowledge -- stays on your machine. no telemetry, no analytics, no phone-home.
  242. ## standing on
  243. swarma exists because of three ideas from three people:
  244. - **[autoresearch](https://github.com/karpathy/autoresearch)** by Andrej Karpathy -- automated research loops where agents iteratively refine their approach. swarma applies this to growth experiments instead of research papers.
  245. - **[QMD](https://github.com/tobi/qmd)** by Tobi Lutke ([@tobi](https://x.com/tobi)) -- shared knowledge across agents. the insight that agents working on different problems should learn from each other.
  246. - **[Hermes](https://github.com/nousresearch/hermes-agent)** by NousResearch ([@NousResearch](https://x.com/NousResearch)) -- the operator layer. an agent that directs teams of specialist agents through tool use. swarma is designed as infrastructure that Hermes operates.
  247. ## roadmap
  248. **shipped:**
  249. - [x] GROWS experiment loop (generate -> run -> observe -> weigh -> stack)
  250. - [x] team generator (`swarma team create --from-goal`)
  251. - [x] 18 squad templates covering full AARRR funnel + 2026 growth ops
  252. - [x] pre-seeded strategy files with real growth knowledge
  253. - [x] external metric ingestion (`swarma metric log/import/show`)
  254. - [x] QMD cross-team wiring (verdict -> playbook -> shared knowledge)
  255. - [x] MCP server (16 tools) for Hermes / Claude Code / any client
  256. - [x] `pip install swarma` on PyPI (v0.2.0)
  257. **next:**
  258. - [ ] dashboard UI (experiment viewer, playbook, strategy evolution)
  259. - [ ] setup wizard (guided onboarding for first-time users)
  260. - [ ] expert reasoning lenses (bundled thinking frameworks)
  261. - [ ] Hermes skill package
  262. - [ ] squad marketplace (share and discover validated teams + playbooks)
  263. - [ ] webhook metric ingestion (real-time analytics callbacks)
  264. - [ ] observation-mode experiments (real-world signal primary, LLM eval secondary)
  265. ## contributing
  266. swarma is early and moving fast. see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  267. short version: open an issue first for anything non-trivial. PRs welcome for bug fixes, new squad templates, and documentation. if you're building a squad that works, we want it in `examples/`.
  268. ## star history
  269. <a href="https://www.star-history.com/?repos=glitch-rabin%2Fswarma&type=date&logscale=&legend=top-left">
  270. <picture>
  271. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=glitch-rabin/swarma&type=date&theme=dark&logscale&legend=top-left" />
  272. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=glitch-rabin/swarma&type=date&logscale&legend=top-left" />
  273. <img alt="Star History Chart" src="https://api.star-history.com/image?repos=glitch-rabin/swarma&type=date&logscale&legend=top-left" />
  274. </picture>
  275. </a>
  276. ## license
  277. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.