Agents

---
name: agents
description: Launch parallel Claude Code agents, each working autonomously on tasks in their own git worktrees
allowed-tools: Bash, Task, Read, Write, Glob, Grep, Edit, WebFetch, AskUserQuestion, ToolSearch
---

# /agents — Parallel Agent Orchestrator

You are the orchestrator. You will launch 1-10 parallel Claude Code agents, each working autonomously on a beads task in its own git worktree. Follow these phases exactly.

**Arguments:** `$ARGUMENTS`

---

## Phase 1 — Parse Arguments & Fetch Tasks

Parse the following flags from `$ARGUMENTS` (all optional):

| Flag | Default | Description |
|------|---------|-------------|
| `--auto-merge` | off | Agents auto-merge PRs after CI passes |
| `--count N` | (interactive) | Max number of tasks to select |
| `--model MODEL` | `sonnet` | Model for spawned agents (ignored when `--agent` is set, since the agent definition specifies its own model) |
| `--budget N` | `5` | Max USD per agent |
| `--agent NAME` | (none) | Use an existing agent definition from `.claude/agents/NAME.md`. Multiple instances of the same agent run concurrently — the file is a reusable template, not a per-instance resource. |

### Fetch tasks

First, check if `bd` (beads) is available:

```bash
command -v bd

If bd is available, fetch tasks:

bd ready --json

Then continue to Phase 2 with the beads task list.

If bd is NOT available (or returns no tasks), offer a manual task mode. Ask the user to describe the tasks they want agents to work on. Accept a list of task descriptions, one per agent. For example:

No beads tasks found. You can specify tasks manually.

How many agents do you want to launch? Enter task descriptions (one per line, empty line to finish):

  1. Fix the login page redirect bug
  2. Add unit tests for the payment module
  3. Refactor the database connection pool

For manual tasks, generate synthetic task IDs (e.g., TASK-1, TASK-2, etc.) and use the descriptions as both the title and description in later phases.

---

Phase 2 — Select Tasks

If using beads tasks, present them as a numbered list:

Available tasks:
  1. [BD-123] Fix auth token refresh logic
  2. [BD-456] Add pagination to /api/users
  3. [BD-789] Update error messages for form validation
  ...

Ask the user to pick tasks. Accept:

• Individual numbers: 1 3 5
• Ranges: 1-5
• all (capped at --count if provided, otherwise 10)

If using manual tasks, the user already specified them in Phase 1 — skip straight to confirmation.

Confirm the selection before proceeding:

Will launch 3 agents:
  1. [BD-123] Fix auth token refresh logic
  2. [BD-456] Add pagination to /api/users
  3. [BD-789] Update error messages for form validation

Agent: parallel-task-worker | Model: sonnet | Budget: $5/agent | Auto-merge: off

Proceed? (y/n)

---

Phase 3 — Setup Worktrees

For each selected task:

1. Create worktree using the glancey create_worktree MCP tool:

   • short_name: sanitized short name from task title (lowercase, hyphens, max 30 chars)
   • issue_id: the task ID (e.g., BD-123 for beads, or TASK-1 for manual tasks)

2. Claim the task (beads tasks only — skip for manual tasks):

   bd update {task_id} --claim
   

3. Record the worktree path returned by create_worktree for Phase 4.

---

Phase 4 — Spawn Agents

CRITICAL: NEVER create files in .claude/agents/. Agent definitions are reusable templates — the same definition supports multiple concurrent instances. If --agent is specified, the file MUST already exist. If it doesn't, tell the user and stop.

For each worktree, do the following:

4a. Write task-specific prompt to temp file

Write the task-specific prompt (see Agent Prompt Template below) to /tmp/agent-prompt-{task_id}.txt. This avoids shell argument length limits.

4b. Build MCP config

Create an inline MCP config JSON that points glancey at the worktree. Write it to /tmp/agent-mcp-{task_id}.json:

{
  "mcpServers": {
    "glancey": {
      "command": "npx",
      "args": ["-y", "glancey@latest"],
      "env": {
        "GLANCEY_PROJECT": "{worktree_path}"
      }
    }
  }
}

4c. Launch the agent

If --agent NAME was provided — use the existing agent definition. Each launch creates a new instance of the same agent; the .claude/agents/NAME.md file is a shared template:

claude --agent {agent_name} \
  --permission-mode bypassPermissions \
  --max-budget-usd {budget} \
  --mcp-config /tmp/agent-mcp-{task_id}.json \
  -p "$(cat /tmp/agent-prompt-{task_id}.txt)" \
  > /tmp/agent-{task_id}.log 2>&1 &

Note: --model is omitted because the agent definition specifies its own model. --max-budget-usd still applies as a per-instance cap.

If no --agent flag — use inline prompt mode:

cat /tmp/agent-prompt-{task_id}.txt | claude -p \
  --permission-mode bypassPermissions \
  --model {model} \
  --max-budget-usd {budget} \
  --mcp-config /tmp/agent-mcp-{task_id}.json \
  > /tmp/agent-{task_id}.log 2>&1 &

Store the PID ($!) for monitoring.

4d. Report launch

After all agents are spawned, print a summary:

Launched 3 agents:
  PID 12345 → [BD-123] Fix auth token refresh (worktree: /path/to/worktree)
  PID 12346 → [BD-456] Add pagination (worktree: /path/to/worktree)
  PID 12347 → [BD-789] Update error messages (worktree: /path/to/worktree)

Logs: /tmp/agent-{task_id}.log

---

Phase 5 — Monitor

Poll every 30 seconds:

# Check if each PID is still running
kill -0 {pid} 2>/dev/null && echo "running" || echo "done"

For each completed agent, tail the last 20 lines of its log:

tail -20 /tmp/agent-{task_id}.log

Print status updates as agents complete. Continue until all agents are done or the user interrupts.

---

Phase 6 — Report

When all agents are finished, produce a summary table:

Agent Results:
┌──────────┬───────────────────────────────────┬───