surshar / claude-code
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.
Built by Anthropic · github.com/anthropics
| 1 | # Swarm Coordination Plugin |
| 2 | |
| 3 | Coordinate multi-agent swarms with conflict prevention, status polling, and checkpoint-based orchestration. |
| 4 | |
| 5 | ## The Problem |
| 6 | |
| 7 | When multiple agents work in parallel on the same codebase, they can: |
| 8 | - Edit the same files simultaneously, creating conflicts |
| 9 | - Make changes that overwrite each other |
| 10 | - Get stuck in endless loops trying to "fix" each other's code |
| 11 | - Waste effort with duplicate work |
| 12 | |
| 13 | ## The Solution |
| 14 | |
| 15 | This plugin implements three complementary coordination patterns: |
| 16 | |
| 17 | ### 1. Status Polling (Proactive Monitoring) |
| 18 | |
| 19 | The orchestrator periodically spawns lightweight status-checker agents to monitor swarm health: |
| 20 | - Detect stuck or failed agents early |
| 21 | - Identify file conflicts as they emerge |
| 22 | - Enable dynamic load balancing |
| 23 | - Provide real-time progress visibility |
| 24 | |
| 25 | ### 2. File Claiming (Ownership Convention) |
| 26 | |
| 27 | Agents claim file ownership before editing: |
| 28 | - Prevents multiple agents from editing the same file |
| 29 | - Clear ownership registry in `.claude/file-claims.md` |
| 30 | - Agents skip files claimed by others |
| 31 | - Claims released after completion |
| 32 | |
| 33 | ### 3. Checkpoint-Based Orchestration (Phased Execution) |
| 34 | |
| 35 | Separate swarm execution into controlled phases: |
| 36 | 1. **Planning** - Agents analyze and plan (read-only, parallel) |
| 37 | 2. **Review** - Detect conflicts before implementation |
| 38 | 3. **Resolution** - Resolve conflicts with user input |
| 39 | 4. **Implementation** - Execute with monitoring |
| 40 | 5. **Verification** - Validate results |
| 41 | |
| 42 | ## Quick Start |
| 43 | |
| 44 | ### Using the `/swarm` Command |
| 45 | |
| 46 | ``` |
| 47 | /swarm Implement user authentication with JWT tokens and session management |
| 48 | ``` |
| 49 | |
| 50 | The command will guide you through: |
| 51 | 1. Initializing coordination files |
| 52 | 2. Launching planning agents |
| 53 | 3. Reviewing and resolving conflicts |
| 54 | 4. Executing implementation with monitoring |
| 55 | 5. Verifying completion |
| 56 | |
| 57 | ### Manual Coordination |
| 58 | |
| 59 | For custom workflows, use the individual components: |
| 60 | |
| 61 | 1. Create coordination files: |
| 62 | - `.claude/swarm-status.json` |
| 63 | - `.claude/file-claims.md` |
| 64 | - `.claude/swarm-plans/` |
| 65 | |
| 66 | 2. Include file claiming instructions in agent prompts |
| 67 | |
| 68 | 3. Launch status-checker periodically during execution |
| 69 | |
| 70 | ## Plugin Contents |
| 71 | |
| 72 | ### Commands |
| 73 | - `/swarm [task]` - Full orchestrated swarm workflow |
| 74 | |
| 75 | ### Agents |
| 76 | - `status-checker` - Monitors swarm health (haiku, fast) |
| 77 | - `conflict-detector` - Analyzes plans for conflicts |
| 78 | - `plan-reviewer` - Validates individual agent plans |
| 79 | |
| 80 | ### Skills |
| 81 | - `swarm-patterns` - Documentation and examples |
| 82 | |
| 83 | ## Coordination Files |
| 84 | |
| 85 | ### `.claude/swarm-status.json` |
| 86 | ```json |
| 87 | { |
| 88 | "swarm_id": "feature-impl-001", |
| 89 | "task": "Implement new feature", |
| 90 | "phase": "implementing", |
| 91 | "agents": { |
| 92 | "agent-1": {"status": "working"}, |
| 93 | "agent-2": {"status": "completed"} |
| 94 | } |
| 95 | } |
| 96 | ``` |
| 97 | |
| 98 | ### `.claude/file-claims.md` |
| 99 | ```markdown |
| 100 | | Agent ID | File Path | Claimed At | Status | |
| 101 | |----------|-----------|------------|--------| |
| 102 | | agent-1 | src/api/handler.ts | 2025-01-15T10:00:00Z | claimed | |
| 103 | | agent-2 | src/db/schema.ts | 2025-01-15T10:00:00Z | released | |
| 104 | ``` |
| 105 | |
| 106 | ## Best Practices |
| 107 | |
| 108 | 1. **Always use planning phase** - Never skip to implementation |
| 109 | 2. **Resolve all conflicts** - Don't proceed with overlapping claims |
| 110 | 3. **Poll regularly** - Every 30-60 seconds during execution |
| 111 | 4. **Use haiku for status checks** - Fast and cheap |
| 112 | 5. **Release claims promptly** - Don't hold after completion |
| 113 | |
| 114 | ## When to Use |
| 115 | |
| 116 | Use this plugin when: |
| 117 | - Multiple agents need to work on the same codebase |
| 118 | - Tasks require parallel execution for speed |
| 119 | - You've experienced agent conflicts before |
| 120 | - You need visibility into swarm progress |
| 121 | |
| 122 | ## When NOT to Use |
| 123 | |
| 124 | Skip this plugin when: |
| 125 | - Single agent is sufficient |
| 126 | - Agents work on completely separate codebases |
| 127 | - Tasks are purely read-only (no file modifications) |
| 128 | |
| 129 | ## Troubleshooting |
| 130 | |
| 131 | ### Agents Still Conflict |
| 132 | - Ensure all agents include file claiming instructions |
| 133 | - Verify conflict detection ran before implementation |
| 134 | - Check that claims registry is being read |
| 135 | |
| 136 | ### Status Checker Shows Stuck Agents |
| 137 | - Check agent logs for errors |
| 138 | - Consider increasing timeout |
| 139 | - May need to reassign work |
| 140 | |
| 141 | ### Claims Not Releasing |
| 142 | - Verify agent completion is being tracked |
| 143 | - Manually update claims if needed |
| 144 | - Check for orchestrator errors |
| 145 | |
| 146 | ## Learn More |
| 147 | |
| 148 | See the `swarm-patterns` skill for detailed documentation: |
| 149 | - `references/status-polling.md` - Polling patterns |
| 150 | - `references/file-claiming.md` - Claiming conventions |
| 151 | - `references/checkpoint-flow.md` - Phased orchestration |
| 152 | - `examples/simple-swarm.md` - Complete example |