{"id":48565413,"url":"https://github.com/phuryn/swarm-protocol","last_synced_at":"2026-06-09T01:09:16.909Z","repository":{"id":344208105,"uuid":"1180894715","full_name":"phuryn/swarm-protocol","owner":"phuryn","description":"Coordination protocol for agent-first teams. No UI. No sprints. No Jira. Just state sync.","archived":false,"fork":false,"pushed_at":"2026-03-15T08:43:51.000Z","size":2559,"stargazers_count":38,"open_issues_count":5,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T05:02:20.575Z","etag":null,"topics":["agent-coordination","ai-coding","claude-code","codex","cursor","vibe-coding"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phuryn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-13T14:25:07.000Z","updated_at":"2026-04-17T06:05:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/phuryn/swarm-protocol","commit_stats":null,"previous_names":["phuryn/swarm-protocol"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/phuryn/swarm-protocol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phuryn%2Fswarm-protocol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phuryn%2Fswarm-protocol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phuryn%2Fswarm-protocol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phuryn%2Fswarm-protocol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phuryn","download_url":"https://codeload.github.com/phuryn/swarm-protocol/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phuryn%2Fswarm-protocol/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34086771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-coordination","ai-coding","claude-code","codex","cursor","vibe-coding"],"created_at":"2026-04-08T13:00:22.272Z","updated_at":"2026-06-09T01:09:16.886Z","avatar_url":"https://github.com/phuryn.png","language":"TypeScript","funding_links":[],"categories":["Multi-Agent Swarms"],"sub_categories":[],"readme":"# 🐝 Swarm Protocol\n\n[![Tests](https://github.com/phuryn/swarm-protocol/actions/workflows/test.yml/badge.svg)](https://github.com/phuryn/swarm-protocol/actions/workflows/test.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-0d9488?style=flat-square)](https://github.com/phuryn/swarm-protocol/blob/main/LICENSE)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-0d9488?style=flat-square)](https://github.com/phuryn/swarm-protocol/blob/main/CONTRIBUTING.md)\n\n**Coordination protocol for agent-first teams. No UI. No sprints. No Jira. Just state sync.**\n\n**Status: Alpha — building in public. [19 MCP tools](#all-19-tools) implemented, integration tests passing.**\n\n## The Coordination Loop\n\nDrop [`COORDINATION.md`](claude-md/COORDINATION.md) into your repo's `CLAUDE.md` and agents coordinate automatically:\n\n```\nAgent starts session\n  → get_team_status        \"What's in flight?\"\n  → claim_work             \"I'm taking this — here are my files\"\n  → check_conflicts        \"Anyone else touching src/api/router.ts?\"\n  → heartbeat              \"Still working\" (every 10-15 min)\n  → complete_claim          \"Done — this unblocks intent_xyz\"\n                              ↳ intent_xyz status: blocked → open\n                              ↳ Next agent picks it up automatically\n```\n\nZero Slack messages. Zero status meetings. Agents coordinate through shared state.\n\n## What This Is\n\nA headless coordination layer exposed as an MCP server — the same protocol Claude Code already speaks. No REST API. No dashboard. Agents query it to see what's in flight, claim work, detect file conflicts, and hand off unblocked tasks.\n\nThis is a **coordination protocol, not a project management tool.** Jira was built for humans clicking buttons. This is state synchronization infrastructure for teams where agents are the primary development interface.\n\nThe CLAUDE.md integration pattern is as important as the server itself. Agents coordinate automatically without humans configuring anything.\n\n## How This Relates to Agent Teams, Code Review, and Other Multi-Agent Tools\n\nThese tools are complementary, not competing. They operate at different layers:\n\n- **Claude Code Agent Teams** coordinates agents within a single session — one lead, parallel teammates, shared task list. Intra-session.\n- **Claude Code Review** dispatches parallel review agents against a single PR. Intra-PR.\n- **VS Code multi-agent** runs Claude, Codex, and Copilot agents side by side for one developer. Intra-machine.\n- **AgentConductor** dynamically adjusts agent communication graphs per coding problem. Intra-problem.\n\n**Swarm Protocol** coordinates across sessions — multiple humans, each running their own agents, on a shared codebase. Inter-session, inter-human.\n\nAn agent uses Agent Teams internally for its own subtask parallelism. It uses Swarm Protocol's MCP tools to know which work to pick up, which files to avoid, and what context the previous agent left behind.\n\nThe single-player problem is getting solved. The multiplayer problem hasn't started.\n\n## Who Is This For\n\nTeams of 2+ developers where AI agents (Claude Code, etc.) are the primary development interface. If your workflow is \"open terminal → tell Claude Code what to build → review the PR\" and teammates are doing the same thing at the same time — this is the missing layer.\n\n**Not for:** solo devs running multiple agents in parallel (tools like [CCPM](https://github.com/automazeio/ccpm) and [1Code](https://www.1code.io/) solve that). Not a Jira replacement. Not a project management tool.\n\n## The Problem\n\nEvery existing tool solves: **\"I'm one developer running 3-5 agents in parallel, how do I prevent them from colliding?\"**\n\nNobody is solving: **\"We're a team of 8 humans, each working through agents, across the same codebase. How do we know what's in flight, avoid stepping on each other, and automatically hand off unblocked work?\"**\n\nThat's single-player vs. multiplayer. Different product category. And it's not a project management problem — it's a state synchronization problem.\n\nWhat happens without coordination:\n- Two agents edit the same files → ugly merge conflicts\n- Completed work sits idle — no one picks up the next dependent task\n- Context is lost between agent sessions\n- No shared state of what's done, in progress, or blocked\n\nSee [LANDSCAPE.md](docs/LANDSCAPE.md) for the full competitive breakdown.\n\n## Four Primitives\n\n| Primitive | What It Does |\n|-----------|-------------|\n| 🎯 **Intent** | A unit of desired outcome — not a ticket. Lifecycle: `draft → open → claimed → done`. Has constraints, acceptance criteria, and dependency chains. |\n| 🔒 **Claim** | \"I'm working on this.\" Tracks which files are being touched. Heartbeat every 10-15 min — stale claims get flagged. |\n| ⚡ **Signal** | Event notification: completion, blocked, conflict. When a completion signal fires, dependent intents auto-unblock. |\n| 📦 **Context Package** | Everything an agent needs to start work — assembled in one call via `get_context`. Solves state handoff: structured output travels with the task so Agent B gets a stable input contract, not just \"the file changed.\" |\n\n## Architecture\n\n![Architecture](docs/architecture.png)\n\n**Stack:** Node.js + TypeScript · PostgreSQL (raw SQL, no ORM) · `@modelcontextprotocol/sdk`\n\n**Design decisions:**\n- Conflicts are advisory, not enforced — no file-level locking\n- Auth is trust-based in v1 (`claimed_by` is a string the agent passes)\n- Single PostgreSQL instance (designed for \u003c1000 users)\n- Polling via MCP tools, no WebSocket subscriptions\n- Protocol over product — minimal and composable by design\n\n## Key Tools\n\n### `check_conflicts` — Prevent file collisions before they happen\n\n```\n→ check_conflicts({ files: [\"src/api/router.ts\", \"src/middleware/auth.ts\"] })\n\n← { conflicts: [{\n     file: \"src/api/router.ts\",\n     claimed_by: \"anna\",\n     intent: \"Refactor API error handling\",\n     claim_id: \"claim_abc123\"\n   }]}\n```\n\n### `get_context` — One call, full onboarding\n\n```\n→ get_context({ intent_id: \"intent_abc123\" })\n\n← { intent: { title, description, constraints, acceptance_criteria },\n    parent: null,\n    dependencies: [{ id: \"intent_xyz\", status: \"done\" }],\n    active_claims: [{ file: \"src/middleware/rateLimit.ts\", claimed_by: \"pawel\" }],\n    recent_signals: [...],\n    team_conventions: \"Use Prettier. Tests required. No console.log in production.\" }\n```\n\n### `complete_claim` — Done. Dependents auto-unblock.\n\n```\n→ complete_claim({ claim_id: \"claim_def456\", unblocks: [\"intent_xyz\"] })\n\n← intent_abc123: claimed → done\n   intent_xyz: blocked → open  (all dependencies met)\n   signal: completion created\n```\n\n### All 19 Tools\n\n\u003cdetails\u003e\n\u003csummary\u003eFull tool reference\u003c/summary\u003e\n\n| Group | Tools |\n|-------|-------|\n| **Teams** | `create_team`, `list_teams`, `get_team_status`, `get_overview` |\n| **Intents** | `create_intent`, `publish_intent`, `list_intents`, `get_intent`, `update_intent`, `decompose_intent` |\n| **Claims** | `claim_work`, `heartbeat`, `release_claim`, `complete_claim` |\n| **Conflicts** | `check_conflicts` |\n| **Signals** | `send_signal`, `get_signals` |\n| **Context** | `get_context` |\n\nSee [SPEC.md](docs/SPEC.md) for full parameter specs and data model.\n\n\u003c/details\u003e\n\n## Quick Start\n\n**Prerequisites:** Docker, Node.js 22+\n\n```bash\n# Clone and set up\ngit clone https://github.com/phuryn/swarm-protocol.git\ncd swarm-protocol\n\n# Start PostgreSQL\ndocker compose up -d\n\n# Build and test\nnpm install\nnpm run build\nnpm test\n```\n\n**Add to Claude Code** (`~/.claude/config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"swarm-protocol\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/swarm-protocol/dist/index.js\"],\n      \"env\": {\n        \"DATABASE_URL\": \"postgresql://postgres:postgres@localhost:5432/swarm_protocol\"\n      }\n    }\n  }\n}\n```\n\n**Enable automatic coordination** — copy [`claude-md/COORDINATION.md`](claude-md/COORDINATION.md) into your repo's `CLAUDE.md`. That's it.\n\n## What's Not in v1\n\nIntentional omissions, not missing features:\n\n- **No web UI** — agents and terminal are the interface\n- **No auth** — trust-based identity. Auth layer comes when it needs to.\n- **No real-time subscriptions** — MCP polling is sufficient\n- **No notifications** — Slack/Discord integration is a natural v2 extension\n- **No file locking** — conflicts are advisory by design\n- **No multi-repo** — single repo per team assumed\n\n## Looking for Co-Builders\n\nThe market for agent-team coordination is tiny today and enormous in 12-18 months. Every team adopting Claude Code, Codex, or similar tools will hit this exact problem the moment they scale past one developer.\n\nThis isn't a side project looking for drive-by PRs. It's a category that needs to be built. I'm looking for people who want to **own parts of this protocol** — lead feature areas, review PRs, shape the design.\n\n**Where to plug in:**\n\n- **Tool groups** (`src/tools/`) are natural ownership boundaries — each one is a self-contained module with its own tests\n- **The protocol design itself** — the four primitives are v1. What's missing? What's wrong? Open an issue and make the case.\n- **Adapters** — SQLite backend, auth layer, Slack signal forwarding, dashboard read-model. Each is a standalone contribution.\n- **The CLAUDE.md pattern** — better coordination instructions, support for other agents beyond Claude Code\n\nThe raw SQL + no-framework design is intentional — fork it, swap PostgreSQL for SQLite, add auth, build custom tools.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Or just open an issue with your idea.\n\n## Docs\n\n| Doc | What's In It |\n|-----|-------------|\n| [SPEC.md](docs/SPEC.md) | Full protocol design, data model, SQL schema, tool specifications |\n| [LANDSCAPE.md](docs/LANDSCAPE.md) | Competitive analysis — every tool in the space and why this is different |\n| [TESTING.md](docs/TESTING.md) | Test architecture, coverage, assumptions |\n| [COORDINATION.md](claude-md/COORDINATION.md) | Drop-in CLAUDE.md snippet for your repo |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphuryn%2Fswarm-protocol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphuryn%2Fswarm-protocol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphuryn%2Fswarm-protocol/lists"}