Multi-agent orchestration through filesystem communication. Launch multiple AI agents, give them the same goal, and watch them self-organize into a team that builds, tests, reviews, and ships features autonomously.
Works with any AI agent — Claude Code, Codex, Cursor, Gemini CLI, Aider, and more. No special APIs required. Pure filesystem communication.
npx skills add bo5amis/swarmThis installs the skill into whichever AI agent you're using (Claude Code, Cursor, Codex, etc.).
- You launch 2+ AI agents (any mix of providers)
- You paste the same goal to all of them
- One agent is designated as the orchestrator, the rest are workers
- They communicate through a
.swarm/directory using a file-based protocol - They autonomously: build a PRD, break it into tasks, implement, test, review, and create a PR
No human intervention needed after the initial prompt.
npx skills add bo5amis/swarmYou are the orchestrator of a multi-agent swarm.
Your goal: [DESCRIBE YOUR GOAL HERE]
Follow the swarm skill protocol. Initialize the swarm and coordinate all agents.
You are a worker in a multi-agent swarm.
Your goal: [SAME GOAL AS ABOVE]
Follow the swarm skill protocol. Register with the swarm and wait for your role assignment.
The agents will:
- Register and get assigned roles (architect, backend expert, reviewer, etc.)
- Draft and agree on a PRD
- Break the PRD into tasks with dependencies
- Implement all tasks in parallel
- Review and test everything
- Create a draft PR
.swarm/ (gitignored, created at runtime)
├── state.json Global phase tracking
├── agents/ Agent registration files
├── board/ Shared documents (PRD, reviews)
├── tasks/ Task definitions and index
├── messages/ JSONL inboxes per agent + broadcast
└── locks/ File locks for task claiming
- Messages: Append-only JSONL files (one per agent + broadcast channel)
- State: Single
state.jsonmanaged by the orchestrator - Tasks: Individual JSON files with a master index
- Locks: Simple lock files for atomic task claiming
- Heartbeats: Agents update their registration file each loop iteration
| # | Phase | What Happens |
|---|---|---|
| 0 | Registration | Agents register, get assigned roles |
| 1 | PRD | Orchestrator drafts PRD, team reviews and approves |
| 2 | Tasks | PRD broken into tasks, assigned to agents |
| 3 | Implementation | Agents build the feature in parallel |
| 4 | Review | Code review, testing, fix loops |
| 5 | PR | Create branch and draft PR |
The orchestrator assigns roles based on the goal:
- Architect — System design and technical decisions
- Backend Expert — APIs, database, server logic
- Frontend Expert — UI components, client-side logic
- UI/UX Expert — Design, interaction patterns, accessibility
- Test Engineer — Writing and running tests
- Code Reviewer — Code quality, security, best practices
- DevOps Engineer — Deployment, CI/CD, infrastructure
Small teams get multiple roles. Large teams specialize.
Any agent that can read and write files works with Swarm. Tested with:
| Agent | Status |
|---|---|
| Claude Code | Fully supported |
| Codex (OpenAI) | Fully supported |
| Cursor | Fully supported |
| Gemini CLI | Fully supported |
| Aider | Fully supported |
| Windsurf | Fully supported |
| GitHub Copilot | Fully supported |
Shell commands (git, test runners) are optional. Agents declare their shell capability at registration. Shell-capable agents handle git operations and test execution.
Q: How many agents should I use? A: 2-5 works best. 2 for small tasks (orchestrator + worker). 3-4 for medium features. 5+ for large features with distinct frontend/backend/testing needs.
Q: Can I mix agents from different providers? A: Yes. That's the whole point. Use Claude Code as orchestrator, Codex for backend, Cursor for frontend — whatever combination you want.
Q: What if an agent crashes? A: The orchestrator detects stale heartbeats (>60s) and reclaims their tasks. Other agents pick up the work.
Q: What if the orchestrator crashes?
A: In v1, the swarm stalls. Restart the orchestrator — it reads .swarm/state.json and resumes from the current phase.
Q: Does this cost more tokens? A: Yes. Each agent has its own context window. Expect 2-4x the token cost of a single agent, depending on team size. The tradeoff is faster, higher-quality output with built-in review.
Q: Can I use this for bug fixes too? A: Yes. The orchestrator adapts the workflow to the goal. For a simple bug fix, it might skip the PRD phase and go straight to tasks.
MIT