Skip to content

Multi-Agent Queue

When processing large epics, nspec supports parallel execution via the agent assignment queue. The queue distributes specs to multiple agents with atomic claim/release and lease-based timeout recovery.

Workflow

# 1. Initialize queue from backlog
nspec queue init --epic E002 --max-agents 5

# 2. Each agent claims a spec
nspec queue claim --agent-id worker-1

# 3. Agent works on the spec, sends periodic heartbeats
# (via MCP: queue_heartbeat)

# 4. Agent releases spec when done
nspec queue release --agent-id worker-1 --spec-id S042 --completed

# 5. Check overall progress
nspec queue status

MCP Tools

Tool Purpose
queue_init Initialize queue from eligible specs
queue_claim Atomically claim next unclaimed spec
queue_release Release spec (back to queue or completed)
queue_heartbeat Extend lease to prevent timeout
queue_status Show agents, queued specs, completed

Configuration

[queue]
mode = "single"                        # "single" or "multi"
max_agents = 5                         # Max concurrent agents
lease_ttl_seconds = 300                # Lease timeout before auto-release

How It Works

  1. Queue initialization scans the backlog for eligible specs (unblocked, not yet claimed) and creates a queue file
  2. Claiming is atomic — uses file-based locking (.novabuilt.dev/nspec/locks/queue.lock) to prevent double-assignment
  3. Heartbeats extend the lease TTL, preventing the queue from reclaiming a spec that's still being worked on
  4. Timeout recovery — if an agent crashes or stops sending heartbeats, its spec is automatically released back to the queue after lease_ttl_seconds
  5. Release marks the spec as completed or returns it to the queue for another agent

Swarm Orchestration

For higher-level parallel execution, nspec provides a swarm orchestrator that manages agent lifecycle on top of the queue. The swarm handles git worktree creation, tmux session management, and automatic teardown.

Tool Purpose
swarm_launch Initialize queue, create worktrees, spawn Claude Code agents
swarm_status Check agent health, tmux sessions, completed specs
swarm_teardown Kill agents, remove worktrees, release claims, clear state 
[claude_code]
model = "sonnet"                       # Model for swarm agents
permission_mode = "bypassPermissions"  # Agent permission mode
timeout = 1800                         # Agent timeout (seconds)
worktree_base = ".worktrees"           # Git worktree directory

Launch a swarm via the /nloop skill:

/nloop E005 with sonnet agent swarm

Each swarm agent works in an isolated git worktree on branch nspec/claude-{i}, preventing merge conflicts between parallel agents.

Scaling

The queue system works well for 2–10 concurrent agents. Each agent independently:

  1. Claims a spec
  2. Runs the /ngo workflow (resolve, implement, test, review)
  3. Releases the spec
  4. Claims the next one

No coordination between agents is needed beyond the queue itself.