# Swarm Coordinator

> Coordinate multiple Claude Code sessions working on the same project via shared task list. Creates task DAG, assigns work to parallel agents, monitors progress. Use for large implementations that benefit from true parallelism. Use when this capability is needed.

- Skill: `tomevault-io/swarm-coordinator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/swarm-coordinator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/swarm-coordinator/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/swarm-coordinator

---


# Swarm Coordinator

Orchestrate multiple Claude Code sessions or agents working on the same project through a shared task list.

## Overview

The swarm coordinator uses `CLAUDE_CODE_TASK_LIST_ID` to enable multiple Claude Code instances to share progress state. Each instance can:
- See all tasks via `TaskList`
- Claim unblocked tasks
- Update task status
- Coordinate without conflicts

## When to Use

- Large implementation with many independent tasks
- Want true parallelism (multiple terminal windows)
- Tasks have clear file ownership (no conflicts)
- Implementation plan includes `Parallel: yes` tasks

## Setup Process

### Step 1: Generate Shared Task List ID

```bash
TASK_LIST_ID="swarm-$(date +%Y%m%d-%H%M%S)"
echo "export CLAUDE_CODE_TASK_LIST_ID=$TASK_LIST_ID"
```

Save this ID - all workers need it.

### Step 2: Create Task DAG from Plan

If IMPLEMENTATION_PLAN.md exists:

1. Read plan and parse tasks manually (agent maintains ID mapping)
2. Create all tasks with `TaskCreate`, recording plan ID → system ID mapping
3. Set up dependencies with `TaskUpdate` using mapped system IDs

Output the task graph for user review.

### Step 3: Launch Worker Sessions

Guide user to open additional terminal windows:

```bash
# Terminal 2 (worker)
export CLAUDE_CODE_TASK_LIST_ID=[same-id]
cd [project]
claude

# Terminal 3 (worker)
export CLAUDE_CODE_TASK_LIST_ID=[same-id]
cd [project]
claude
```

### Step 4: Worker Protocol

Each worker follows this loop:

```
1. TaskList to see available work
2. Find unblocked pending task with no owner
3. TaskUpdate to claim (set owner to session ID)
4. TaskUpdate status to in_progress
5. Implement the task
6. Run tests
7. TaskUpdate status to completed
8. Repeat
```

### Step 5: Orchestrator Monitoring

The coordinator (this session) monitors progress:

```
- TaskList every few minutes to see global state
- Identify stuck tasks (in_progress too long)
- Handle blockers and conflicts
- Run final integration tests when all tasks complete
```

## Task Claiming Protocol

To prevent race conditions:

1. Worker calls `TaskUpdate` with `owner: "session-<id>"` for a pending task
2. If another worker claimed it first, the task will have a different owner
3. Worker checks `TaskGet` to verify ownership before proceeding
4. Only the owner can transition to `in_progress` and `completed`

## Conflict Resolution

If two workers modify the same file:

1. First to complete wins
2. Second worker must rebase/resolve conflicts
3. If conflict is complex, coordinator arbitrates

## Completion

When all tasks are `completed`:

1. Coordinator runs full quality gate suite
2. Integration tests across all changes
3. Final code review via `/requesting-code-review`
4. Merge/squash if using worktrees

## Example Session

```
Coordinator: "Starting swarm for auth-system implementation"

TaskList shows:
#1 [pending] Create user model - ready
#2 [pending] Create auth middleware - ready
#3 [pending] Create login endpoint - blocked by #1, #2
#4 [pending] Create register endpoint - blocked by #1
#5 [pending] Add password hashing - blocked by #1

Coordinator assigns:
- Worker 1: Task #1 (user model)
- Worker 2: Task #2 (auth middleware)

Workers complete, TaskList now shows:
#1 [completed] - by worker-1
#2 [completed] - by worker-2
#3 [pending] - now unblocked!
#4 [pending] - now unblocked!
#5 [pending] - now unblocked!

Coordinator assigns next batch...
```

## Limitations

- Works best with clear task boundaries
- File conflicts require manual resolution
- All workers must have same env setup
- Shared task list requires same `CLAUDE_CODE_TASK_LIST_ID`

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/treygoff24) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->