swarm-research
Skill0 starsChanged 43 days agoMITView on GitHub
SwarmResearch (arXiv 2607.02807) — orchestrate a swarm of Claude Code agents on an open-ended optimization problem with a measurable score. You act as the Shepherd: spawn fresh-context Explorers and session-forking Optimizers, each in its own git branch/worktree, keep a global ledger, maintain diversity of high-level approaches, and adapt parallelism per depth. Use when the user says "swarm research", "swarmresearch", "shepherd", "lance un swarm", or wants autoresearch-style long-running discovery (speed up code, improve a heuristic, beat a benchmark score) without converging on a single idea.
2 other projects use a version of this.
Adopted by
Most recently taken up by
- DavidTeju/shared-skillstheir own version, first seen Sep 3, 2026
- dralgorhythm/claude-agentic-frameworktheir own version, first seen Jul 24, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- dralgorhythm/claude-agentic-framework★ 118same name
- DavidTeju/shared-skills★ 9same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repositoryOne other file it gives its agents.
- swarm-prepSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 24
If any is missing, or .swarm/config.md doesn't exist yet, run the swarm-prep skill first (it interviews the user and builds all of this, …
- Very specific: line 34
All agents launch from the repo root (so --resume finds parent sessions) and are told to work only in their worktree.
- Very specific: line 35
Run every spawn with the Bash tool and run_in_background: true — you are notified when each finishes.
- Very specific: line 49
After each agent finishes, read its JSON + the last commit on its branch (git log -1 --format=%s r-NN → "<desc> | score=<x>") and append …
- Distinctive: line 61
Fan-out on plateaus: when a family stops improving (≈2 consecutive non-improving children), stop deepening it.
- Distinctive: line 64
Stop when the Explorer budget is spent (Optimizers are cheap extras, still respect the $ cap) or the user says stop.
- Very specific: line 83
Never let a Search Agent see .swarm/ledger.md or other lineages — shared global memory causes "self-organized collapse" (all agents …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
SwarmResearch — you are the Shepherd
Technique from SwarmResearch: Orchestrating Coding Agents for Open-Ended Discovery (Virk, Edds, Xia, Zhang — arXiv 2607.02807). Single long-running agents converge on one high-level approach then only tweak it. SwarmResearch fixes this with:
- Shepherd (you): global context, steers the search. Never writes solution code. Never prescribes ideas.
- Search Agents: headless
claude -pprocesses, each on its own branch in.worktrees/<branch>, seeing only local context.- Explorer — fresh context window, implements ONE fundamentally new idea. See explorer.md.
- Optimizer — forks its parent's session (inherits full conversation), refines that lineage. See optimizer.md.
- Steering levers (the ONLY three): which parent branch, which agent type, minimal context in the prompt.
Phase 0 — Setup (confirm with the user before spending money)
The target repo needs, on main:
prompt.md— problem statement, constraints, what is forbidden (e.g. editing the evaluator), how to run the eval.- An evaluator command that prints a single numeric score (state if higher or lower is better). Deterministic or averaged; must not be editable by agents (mention it in prompt.md).
- A minimal working baseline solution that the evaluator scores.
If any is missing, or .swarm/config.md doesn't exist yet, run the swarm-prep skill first (it interviews the user and builds all of this, with an anti-gaming holdout). If .swarm/config.md exists, read it and use its settings instead of asking again. Then:
bash ~/.claude/skills/swarm-research/scripts/init.sh # run at repo root: git init if needed, .gitignore, .swarm/Agree with the user on: Explorer budget (paper default: 25), $ cap per agent (--max-budget-usd, e.g. 2–3), max concurrent agents (e.g. 4–6), model. Write them to .swarm/config.md.
Agents run with
--permission-mode bypassPermissions(as in the paper) so they can run the evaluator unattended. Tell the user this and that each agent is confined by instructions (not sandbox) to its worktree. If they refuse, useacceptEdits+--allowedToolsfor the eval command instead (editscripts/spawn.sh).
Phase 1 — Spawning
All agents launch from the repo root (so --resume finds parent sessions) and are told to work only in their worktree.
Run every spawn with the Bash tool and run_in_background: true — you are notified when each finishes.
# Explorer from scratch, or from a parent branch, or multi-parent (comma list → git merge --no-commit)
bash ~/.claude/skills/swarm-research/scripts/spawn.sh explorer r-07 main "<minimal context or empty>"
bash ~/.claude/skills/swarm-research/scripts/spawn.sh explorer r-12 r-03 "<context>"
bash ~/.claude/skills/swarm-research/scripts/spawn.sh explorer r-15 r-03,r-09 "<context>"
# Optimizer: forks the parent's session (parent must have finished)
bash ~/.claude/skills/swarm-research/scripts/spawn.sh optimizer r-13 r-07 "<context>"Branch names: r-NN, never reused. Result JSON lands in .swarm/runs/<branch>.json (has session_id, result, total_cost_usd); the script appends the session id to .swarm/sessions.tsv.
Phase 2 — The ledger (your global context, nobody else sees it)
After each agent finishes, read its JSON + the last commit on its branch (git log -1 --format=%s r-NN → "<desc> | score=<x>") and append one row to .swarm/ledger.md:
| branch | type | parent | family | idea (1 line) | score | status |
family = the high-level approach (you name it: e.g. "greedy+local search", "DP", "SIMD batching"). Families are what you manage, not individual branches. Also keep a short "Families" section: strengths, weaknesses, best score, last improvement time.
Phase 3 — Adaptive scaling policy
You are near-greedy by default (the paper found this explicitly). Fight it.
- Wide start: spend ~30–40% of the Explorer budget on a diverse initial population from
main, launched in small batches (2–4) rather than all at once. - Deepen promising families serially: chains of Optimizers / Explorers on the top 2–3 families, including under-developed ones, not only the current best.
- Fan-out on plateaus: when a family stops improving (≈2 consecutive non-improving children), stop deepening it. Spawn fresh Explorers from diverse parents (
main, other families, multi-parent merges) with plateau context. - Late phase: concentrate remaining budget on refining the best 1–2 families with Optimizers.
- Vary width per depth; never use a fixed n×k grid. Keep ≥2 alive families until the final quarter of the budget.
- Stop when the Explorer budget is spent (Optimizers are cheap extras, still respect the $ cap) or the user says stop.
Phase 4 — How to write the context (most important rule)
Do not suggest or instruct what idea to pursue. Give only context that helps them decide on their own. You may say what NOT to re-explore.
- GOOD: "Your parent scored 0.78, strong on typical cases and speed, but still violates hard constraints on edge cases. Another family reached 0.79 by improving constraint satisfaction, but is less accurate on ordinary cases."
- GOOD (plateau): "Families so far: A (greedy, 0.81, fast, weak on large n), B (DP, 0.79, exact but memory-bound). Both plateaued. Do not re-explore variants of A or B; look for a technique that addresses their limitations."
- BAD: "Implement beam search with a learned scorer and tune beam width in [8,16,32]."
Explorers from main often get no context at all — that maximizes diversity in the initial population.
Phase 5 — Report
At the end (or on request): best branch + score, the family tree (ledger), total cost (sum of total_cost_usd), what failed and why (from findings.md files). Offer to merge the winning branch into a result branch. Review the winning diff yourself for evaluator gaming (hard-coded outputs, edited eval files, constraint violations) before declaring a win — the paper notes careful review is costly but necessary.
Cleanup when the user approves: git worktree prune, remove .worktrees/ entries of dead branches. Never delete branches without asking.
Gotchas
- Never let a Search Agent see
.swarm/ledger.mdor other lineages — shared global memory causes "self-organized collapse" (all agents converge). Onlyfindings.mdtravels along a lineage. - An Optimizer needs its parent to have finished (session must exist). Resume only works because everything launches from repo root.
- Watch total spend; the paper used ~$50/task with 25 Explorers.
- Windows: scripts are POSIX — run them through the Bash tool (Git Bash).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

