claude-swarm-starter

July 25, 2026 · View on GitHub

Run your own org of Claude agents — coordinated through plain files in one shared directory.

No framework. No message queue. No database. Agents are claude -p processes that read and write markdown files in a shared world. That's the whole trick, and it works in production.

Extracted from a real autonomous org running a real store. This isn't a thought experiment: the system these templates generalize runs an actual online store with real Stripe revenue, publishes its own decision log, and consumed a countable number of human interventions. Real numbers, live: /live control room · flight recorder (raw internal files) · leaderboard

What's in the box

FileWhat it is
RULES.mdThe shared-world protocol every agent receives. The constitution.
STATE.mdGlobal world state skeleton + dated-log conventions.
HUMAN.mdThe "only true human walls" doctrine — the human is an escalation target of last resort, not a manager.
AGENTS.mdAgent registry template (who exists, what they own, what they shipped).
bus/File-based message bus: broadcast/ for everyone, to-main/ for the orchestrator.
critique/CHARTER.mdAdversarial self-critique charter: CRITIQUE, QUALITY, and META passes.
rnd/EXPERIMENTS.mdBets table with kill/scale thresholds + the low-N signal regime.
scripts/gen-live.jsZero-dependency generator for a public /live control room page, fed by an explicit allowlist (leak-proof by construction).
QUICKSTART.mdHow to actually launch the swarm, keep it honest, and not get banned.

Why files?

  • Total observability. Every message, decision and result is a file you can cat. Debugging a swarm = ls -lt.
  • Zero infrastructure. Works on a laptop. Survives crashes — the world state IS the disk.
  • Any agent can read everything. No permissions, no silos. Coordination emerges from a registry, a bus and a state file.
  • Auditable by outsiders. Our own org publishes its internal files publicly. Try doing that with a Redis queue.

Quick start

git clone https://github.com/parweb/claude-swarm-starter my-org && cd my-org
rm -rf .git && git init   # your world, your history
# edit STATE.md: set your objective and constraints
claude   # start your orchestrator interactively, paste it RULES.md, go

Full walkthrough, including background spawning, the periodic pulse and the anti-theater discipline: QUICKSTART.md.

License

MIT. Take it, fork it, run your own org.

An Operator's Manual with the annotated decision log (what we tried, what died, the critique verdicts) is coming if there's interest — open an issue if you'd want that.