The .Swarm Protocol

An ecologically-inspired, environment-first coordination protocol for multi-agent AI teams.

No central node. No database. No credentials. Agents leave structured traces; the environment does the coordination.

Documentation · CLI Reference · Agent Roles · GitHub

dot_swarm is a layered toolkit. Every layer is opt-in — start with zero dependencies and add AI, security, roles, and federation only when you need them.

Modern software teams run multiple AI coding agents simultaneously — Claude Code, Cursor, Windsurf, Gemini, opencode — across different repos and sessions. Without coordination:

• Two agents claim and implement the same task simultaneously
• Context is lost when a chat session ends or a context window is compacted
• Non-obvious decisions (why approach A over B) disappear with the session
• The next agent has no idea what the previous one did, decided, or left in-flight

Existing solutions require infrastructure that gets in the way:

• Jira / Linear / GitHub Issues — web UIs, API credentials, no agent-native format
• Database-backed tools — binary files, server processes, another thing to run
• Slack bots / webhooks — async, lossy, not git-auditable

The answer isn't a better tracker. It's a different model entirely.

In nature, complex coordination emerges without central controllers.

A bee queen does not dispatch workers or resolve conflicts. She emits chemical markers that encode colony state, and workers read those traces autonomously to decide what to do next. Ant colonies self-organize task specialization across hundreds of thousands of individuals through the same mechanism: indirect coordination through a shared medium. No bottleneck. No single point of failure. No credentials required.

The key property that makes this work: all members speak the same chemical language. Every worker interprets the environment the same way. The signal is the protocol.

dot_swarm applies this model directly to software agent fleets:

Agents that modify filesystem-native projects should leave traces in their environment for collaborative purposes, rather than reporting to a central node around which complicated systems must be arranged to prevent bottlenecks and data loss from information overload.

The .swarm/ directory is the shared medium. state.md is the pheromone trail. BOOTSTRAP.md is the chemical language every agent reads first. Git is the transport.

Signals decay. swarm audit flags stale claims. memory.md entries are dated. state.md timestamps tell any agent exactly how fresh the picture is.

This isn't another markdown-based task tracker. It's a multi-master, environment-first coordination protocol — inspired by six decades of stigmergy research, built for the reality that AI agent fleets need to self-organize across repos, sessions, and tools without a central authority managing them.

Every repository gets a .swarm/ directory. Five files are the protocol core:

Additional opt-in files: trail.log (signed audit), schedules.md, workflows/, federation/, roles/.

Work items use inline stamps for optimistic concurrency — no lock server needed:

## Active
- [>] [CLD-042] [CLAIMED · claude-code · 2026-03-26T14:30Z] Fix Redis timeout
      priority: high | project: cloud-stability

## Pending
- [ ] [CLD-043] [OPEN] Add request ID tracing to all services
      priority: medium | project: observability
      depends: CLD-042

## Done
- [x] [CLD-041] [DONE · 2026-03-25T16:00Z] Update auth health check path
      project: cloud-stability

swarm ready shows only items whose entire dependency chain is complete:

swarm ready          # list what's safe to pick up right now
swarm ready --json   # machine-readable, for agent scripts

Organization (your-company/)       ← cross-repo initiatives
  .swarm/
├── Division (service-a/)          ← single-repo work
│     .swarm/
└── Division (service-b/)
      .swarm/

Work items use level-prefixed IDs: ORG-001, CLD-042, FW-017. Cross-division items live at org level with refs: pointers in each affected division's queue.

Use swarm ascend and swarm descend to check alignment across levels.

pip install dot-swarm

cd your-repo
swarm init                    # creates .swarm/ with signing identity
swarm add "Fix auth timeout" --priority high
swarm add "Add rate limiting" --depends CLD-001
swarm ready                   # see what's unblocked right now
swarm claim CLD-001
# ... do work ...
swarm done CLD-001 --note "Used exponential backoff"
swarm handoff                 # structured summary for next agent/human

pip install 'dot-swarm[ai]'
swarm configure               # set model + region once

swarm ai "what should I work on next?"
swarm ai "implement the auth module, then the markets module" --chain --max-steps 6

pip install dot-swarm

# Add to ~/.claude/mcp_config.json:
# { "mcpServers": { "dot-swarm": { "command": "dot-swarm-mcp" } } }

# dot_swarm state is now available as MCP tools in your IDE agent

# Enable inspector role — workers must prove completion before done
swarm role enable inspector --max-iterations 3 --require-proof "branch,commit,tests"

# Spawn a worker agent in a named tmux window (auto-claims the item)
swarm spawn SWC-042 --agent opencode

# Worker attaches proof then hands off to inspector
swarm partial SWC-042 --proof "branch:feature/oauth2 commit:abc1234 tests:42/42"

# Spawn inspector and supervisor as dedicated role windows
swarm spawn --role inspector
swarm spawn --role supervisor

# Inspector passes or fails with a reason
swarm inspect SWC-042 --pass
swarm inspect SWC-042 --fail --reason "Edge case in token refresh — see test_auth.py:142"

# If inspect_fails exceeds max_retries, item auto-BLOCKs and surfaces in audit
swarm audit --full

# Walk the working tree and build context for all divisions
swarm crawl                   # writes Directory Map to context.md
swarm crawl --create-items    # also creates queue items for uncatalogued dirs
swarm heal                    # verify alignment after crawl

dot_swarm is distinct from Gastown/Beads in being multi-master (no Mayor bottleneck), feature-toggleable (every layer is opt-in), and federation-capable across separate repos and organizations via signed OGP-lite messages.

dot_swarm and Gastown solve overlapping problems with different tradeoffs:

Both are inspired by Steve Yegge's work and the broader stigmergy literature. dot_swarm was specifically designed to work in environments where you cannot install a database, and where no single agent should be a required coordinator.

Every swarm init generates a per-swarm HMAC-SHA256 signing identity. All AI operations are signed and recorded in trail.log. swarm audit --security and swarm heal scan for 18 adversarial content patterns across three severity levels (CRITICAL / HIGH / MEDIUM) in all .swarm/ files and platform shims.

Inspired by Steve Yegge's "Welcome to Gas Town" and grounded in stigmergy research spanning six decades, from Grassé's termite mound studies (1959) through Dorigo's Ant Colony Optimization (1996) to Bonabeau, Dorigo & Theraulaz's Swarm Intelligence (1999).

MIT — github.com/oasis-main/dot_swarm