agent

name	agent
description	Spawn and manage autonomous background agents with persistent state across sessions
argument-hint	"task" | list | switch <id> | stop <id> | merge <id> | resume <id> | retry <id> | diff <id> | logs <id> | batch | note <id> | watch <id> | rebase <id> | export <id> | stats | history | clean
disable-model-invocation	true
effort	high
allowed-tools	Agent, AskUserQuestion, Bash, Read, Edit, Write, Glob, Grep, TaskOutput, TaskStop, TaskCreate, TaskUpdate, TaskList

Agent Manager v4

Parse $ARGUMENTS and execute the matching command below. Persistent state lives in .claude/agents/registry.json (source of truth). Task system is for live monitoring only.

Pre-flight: Before executing any command, verify the current directory is inside a git repository (git rev-parse --is-inside-work-tree). If not, reject: "Agent manager requires a git repository. Run git init first." Registry: Read .claude/agents/registry.json — if missing/corrupt, default to { "version": 2, "defaultBranch": null, "agents": [] }. If version is 1 or missing, migrate: add model: null, effort: null, color: null, maxTurns: null to each agent entry, add defaultBranch: null at top level, set version to 2, write immediately. Always mkdir -p .claude/agents before writing. Atomic writes: Always write registry to .claude/agents/registry.json.tmp first, then rename to .claude/agents/registry.json. This prevents corruption from interrupted writes. Default branch: Read from registry.defaultBranch. If null (first time using the plugin in this repo), ask the user using AskUserQuestion: "What is your default/base branch? (e.g., main, master, develop)". Store the answer in registry.defaultBranch and write registry. Once set, never ask again. Use {defaultBranch} everywhere in this document instead of a hardcoded branch name. Agent ID: Generate via echo "$(date +%s)$$.$RANDOM" | shasum | head -c 6 (6-char hex). $$ (PID) + $RANDOM ensures uniqueness even when called multiple times in the same second (e.g., batch). Age format: <N>m ago / <N>h ago / <N>d ago relative to createdAt. Prefix match: All ID-based commands support prefix matching. If the prefix is ambiguous (matches multiple agents), reject and show the matching IDs. If no match, show all available IDs. Templates dir: .claude/agents/templates/ — JSON files with required fields { name, description } and optional { verifyCommand, commitFormat }. verifyCommand overrides Phase 4 auto-detection; commitFormat overrides the default conventional commit format. User defaults: If env var CLAUDE_PLUGIN_OPTION_DEFAULT_MODEL is set, use it as default model when --model is not specified. If CLAUDE_PLUGIN_OPTION_DEFAULT_EFFORT is set, use it as default effort level. These are configured when the user enables the plugin. Auto-registry: A SubagentStop hook automatically updates the registry when a worker agent completes. The list command still verifies status as a fallback. Flag validation: --model must be one of haiku, sonnet, opus. --color must be one of red, blue, green, yellow, purple, orange, pink, cyan. --effort must be one of low, medium, high, max. --max-turns must be a positive integer. Reject invalid values with a clear error message listing valid options.

---

list

1. Read registry. If empty, say "No agents found. Spawn one with: /agent "your task""
2. For each agent with status running:
   • If taskId is null → mark as unknown, continue
   • First, check if .claude/agents/<id>-result.txt exists (Read it). If it exists → parse it, update entry to completed with branch/commit/files/completedAt. Continue to next agent.
   • If no result file, try TaskOutput with block: false, timeout: 3000 using stored taskId
   • If task found & completed → check result file again, update to completed
   • If task found & still running → leave status as running, continue
   • If task found & errored → mark as failed
   • If task NOT found (new session) → if branch is null → unknown. Otherwise check git branch --list <branch> — branch exists → unknown, no branch → failed
3. Write updated registry. Display table: ID | Status | Description | Branch | Age

switch <id>

1. Look up agent by ID in registry (prefix match). If not found, show available IDs.
2. If running and taskId is not null → first check result file .claude/agents/<id>-result.txt. If exists, update to completed and show summary. Otherwise try TaskOutput with block: false, timeout: 5000 and display the latest output to the user. If running with null taskId → say "Agent is running but has no task handle (spawn may have partially failed). Try /agent list to refresh or /agent stop <id>."
3. Otherwise → read .claude/agents/<id>-result.txt for summary. If file missing, say "No result file yet. Agent may still be in progress or failed without output."
4. Show: status, description, branch, model (if set), color (if set). Suggest next actions based on status:
   • running → /agent watch <id> or /agent stop <id>
   • completed → /agent merge <id>, /agent diff <id>
   • unknown/stopped → /agent merge <id>, /agent diff <id>, /agent resume <id>
   • failed → /agent retry <id> or /agent resume <id>
   • merged → /agent clean
   • If branch exists (any status), also suggest git diff {defaultBranch}...<branch>

stop <id>

1. Look up agent in registry (prefix match). If not found, say so. If status is not running, reject: "Agent <id> is <status>, not running."
2. If taskId is not null, try TaskStop with task_id (ignore errors if gone). If taskId is null, skip — just update status.
3. Update registry: status → stopped, set completedAt. Write registry. Confirm.

history

1. Read registry. If empty, say "No agent history found"
2. Display ALL agents sorted by createdAt desc. Table: ID | Status | Description | Branch | Commit Message | Model | Date. Show "—" for null/empty fields. Show notes count if agent has notes (e.g., "2 notes").

clean

1. Read registry. Filter agents with status completed/stopped/merged/failed/unknown
2. For each: delete .claude/agents/<id>-result.txt and .claude/agents/<id>.patch (if exists), delete branch if merged and branch is not null (git branch -d <branch>). Ignore errors. (Worktrees from isolation: "worktree" are auto-managed by Claude Code.)
3. Remove entries from registry, write it. Report: "Cleaned up N agent(s). M still running."

merge <id>

1. Look up agent (prefix match). If not found or status not completed/unknown/stopped, reject with reason.
2. If branch is null, reject: "No branch recorded for this agent." Otherwise, verify branch exists (git branch --list <branch>). If not, say so.
3. Check working tree is clean (git status --porcelain). If dirty, reject: "Working tree has uncommitted changes. Commit or stash first."
4. Run git checkout {defaultBranch} && git merge <branch>. On success → update status to merged, write registry, suggest /agent clean. On conflict → tell user, suggest git merge --abort.

---

resume <id>

1. Look up agent in registry (prefix match). Must have status stopped/failed/unknown/completed. Reject if running/merged.
2. If branch is null, say "No branch to resume from. Use /agent retry <id> to start fresh." Otherwise, verify branch exists (git branch --list <branch>). If not, say "Branch no longer exists. Use /agent retry <id> to start fresh."
3. Read .claude/agents/<id>-result.txt — this contains the completion context (branch, files changed, summary of what was done). If missing, fall back to git log {defaultBranch}..<branch> --oneline (1 command only).
4. Update registry: status → running, clear completedAt. Write registry.
5. TaskCreate with subject: Resume: <original description> (60 chars max), activeForm (present continuous).
6. Spawn Agent with subagent_type: "agent-manager:worker", prompt:

You are RESUMING previous work. **Task:** {description} | **Agent ID:** {id}

**Previous work summary:**
{result file contents}

**Resume instructions:**
- Fetch and checkout the existing branch: `git fetch origin {branch} 2>/dev/null; git checkout {branch} 2>/dev/null || git checkout -b {branch} origin/{branch} 2>/dev/null || echo "Warning: branch {branch} not found"`
- Read the changed files and understand what was already completed
- Identify what remains to be done vs what is already done
- Do NOT redo completed work — only pick up where it left off
- Then proceed through the standard phases (Plan, Implement, Verify, Commit)
{if verifyCommand}

**Verify command:** `{verifyCommand}`
{end}
{if commitFormat}

**Commit format:** `{commitFormat}`
{end}

**CRITICAL — after committing, write the result file to the ORIGINAL repo (not worktree):**

BRANCH=$(git rev-parse --abbrev-ref HEAD)
COMMIT=$(git rev-parse --short HEAD)
COMMIT_MSG=$(git log -1 --pretty=%s)
FILES=$(git diff {defaultBranch}..HEAD --name-only 2>/dev/null | tr '\n' ', ' | sed 's/,$//')
DIFF_STAT=$(git diff {defaultBranch}..HEAD --stat 2>/dev/null | tail -5)
COMMIT_LOG=$(git log {defaultBranch}..HEAD --oneline 2>/dev/null)
mkdir -p {repo_absolute_path}/.claude/agents
cat > {repo_absolute_path}/.claude/agents/{id}-result.txt << RESULT_EOF
branch: $BRANCH
commit: $COMMIT
commitMessage: $COMMIT_MSG
filesChanged: $FILES
summary: Resumed and completed task — {short description}
commitLog: $COMMIT_LOG
diffStat: $DIFF_STAT
RESULT_EOF

Template handling (same as Spawn): Read verifyCommand and commitFormat from the registry entry. Include {if ...} blocks only when the value is set. Remove {if}/{end} markers from the final prompt. Also pass model from registry entry if set (via Agent tool's model parameter).

7. Update registry entry's taskId from the background Agent task. Write registry.
8. Tell user: agent <id> resumed on branch <branch>.

retry <id>

1. Look up agent in registry (prefix match). Must have status stopped/failed/unknown. Reject otherwise.
2. Save the original description, verifyCommand, commitFormat, model, effort, color, and maxTurns from the entry.
3. Generate a NEW agent ID.
4. Add new entry to registry (using standard schema from Spawn step 4) with original description and all saved fields, status running. Write registry.
5. Run TaskCreate (subject, description, activeForm) then spawn Agent (same params as Spawn step 5, passing through all saved fields). Update the entry's taskId from the Agent task. Write registry.
6. Tell user: "Retrying as new agent <new_id> (original: <old_id>). Original agent preserved in history."

diff <id>

1. Look up agent in registry (prefix match). If not found, show available IDs.
2. Get the branch name. If no branch, reject: "No branch found for this agent."
3. Run git diff {defaultBranch}...<branch> --stat to show file-level summary.
4. Run git diff {defaultBranch}...<branch> to show full diff.
5. Display the stat summary first, then the full diff (truncate if extremely long — show first 200 lines and note if truncated).

logs <id>

1. Look up agent in registry (prefix match).
2. Read .claude/agents/<id>-result.txt — display if exists.
3. If taskId is not null, find the agent's subagent transcript: search for files matching ~/.claude/projects/*/subagents/agent-*.jsonl using Glob. Look for the transcript that corresponds to the agent's taskId. If taskId is null, skip to step 5.
4. If transcript found, read it and extract a summary:
   • List tools used (Read, Write, Edit, Bash, etc.) with counts
   • Show files read/modified
   • Show bash commands executed
   • Show any errors encountered
5. If no transcript found and branch is not null, check git log on the branch: git log {defaultBranch}..<branch> --oneline --stat. If branch is null, say "No branch or transcript available."
6. Display: Agent ID | Status | Description | Activity Summary | Files Touched | Errors (if any)

batch "task1" "task2" ...

1. Parse arguments — use shell-style quote parsing. Each quoted string is a separate task description. Unquoted words are joined as a single task. If no tasks parsed, reject: "Usage: /agent batch \"task one\" \"task two\" ..."
2. For each task: generate a unique ID, add entry to registry (using standard schema from Spawn step 4) with status running. Write registry once with all new entries.
3. For each task: run TaskCreate (subject, description, activeForm) then spawn Agent (same params as Spawn step 5). Update the entry's taskId from the Agent task. Write registry after each spawn to persist taskId.
4. Display table of all spawned agents: ID | Description | Status
5. Tell user: "Spawned {N} agents. Use /agent list to monitor."

Batch flags: batch also supports --model, --effort, and --max-turns flags. If provided, they apply to ALL agents in the batch. Place flags before the task strings: /agent batch --model sonnet "task one" "task two".

note <id> "text"

1. Look up agent in registry (prefix match).
2. Parse the note text from arguments (everything after the ID). If no text provided, reject: "Usage: /agent note <id> \"your note text\""
3. Add/append to a notes array in the registry entry: { text, timestamp: <ISO now> }.
4. Write registry. Confirm: "Note added to agent <id>."
5. When displaying agent details (in switch, history), show notes if present.

watch <id>

1. Look up agent in registry (prefix match). Must have status running. Reject otherwise.
2. If taskId is null, reject: "Agent has no task handle. Try /agent list to refresh status."
3. Tell user: "Watching agent <id>... (up to 5 minutes, Ctrl+C to stop)"
4. Try TaskOutput with block: true, timeout: 300000 (single blocking call, 5 minutes max). If TaskOutput fails or is unavailable (deprecated), fall back to polling: check .claude/agents/<id>-result.txt every 10 seconds using Bash(sleep 10) + Read, for up to 30 iterations (5 minutes). If the result file appears during polling, treat as completed.
5. Handle the result:
   • If completed → parse result file (if missing, update registry to completed with no file details and note "Result file not found — agent may have failed to write it")
     • If branch is not null, run git diff {defaultBranch}...<branch> --stat to preview changes. If branch is null, say "Agent completed but no branch was recorded."
     • Show the diff summary to the user
     • Ask user explicitly: "Agent completed. Merge branch <branch> into current branch?" — wait for confirmation. Do NOT auto-merge. (Skip merge prompt if branch is null.)
     • If user confirms → check working tree is clean (git status --porcelain), then run git merge <branch>. On success → update status to merged, write registry, suggest /agent clean. On conflict → tell user, suggest git merge --abort
     • If user declines → tell user: "Skipped merge. Use /agent merge <id> later or /agent diff <id> to review."
   • If errored → update registry to failed, write registry. Tell user: "Agent failed. Use /agent logs <id> to investigate or /agent retry <id> to try again."
   • If still running (timeout reached) → say: "Agent still running after 5 minutes. Use /agent watch <id> again or /agent list to check."

rebase <id>

1. Look up agent in registry (prefix match). Must have status completed/unknown/stopped. Reject if running/merged/failed with reason.
2. If branch is null, reject: "No branch recorded for this agent." Otherwise, verify branch exists (git branch --list <branch>). If not, say so.
3. Check working tree is clean (git status --porcelain). If dirty, reject: "Working tree has uncommitted changes. Commit or stash first."
4. Run git fetch origin {defaultBranch} (ignore errors if no remote).
5. Run git checkout <branch> && git rebase {defaultBranch}.
6. On success → run git checkout - to return to original branch. Tell user: "Branch <branch> rebased onto {defaultBranch}. Ready to merge with /agent merge <id>."
7. On conflict → tell user the conflicting files, suggest git rebase --abort or manual resolution.

export <id>

1. Look up agent in registry (prefix match).
2. Get branch name. If no branch, reject.
3. Run mkdir -p .claude/agents && git format-patch {defaultBranch}..<branch> --stdout > .claude/agents/<id>.patch
4. Tell user: "Patch exported to .claude/agents/<id>.patch. Apply with git am < .claude/agents/<id>.patch."

stats

1. Read registry.
2. Calculate:
   • Total spawned: count of all agents
   • By status: count per status (running/completed/stopped/failed/merged/unknown)
   • Success rate: completed+merged / total (exclude running). If no non-running agents, show "N/A"
   • Most active day: group by date of createdAt, find max
   • Avg files changed: average length of filesChanged arrays (for completed/merged). If none, show "N/A"
   • Models used: count per model value (for agents with model set)
3. Display as a formatted summary panel.

---

Spawn (default — no command match)

Handles: plain task descriptions, --template <name>, --model <model>, --effort <level>, --color <color>, and --max-turns <N> flags.

1. Parse flags from arguments:
   • --template <name>: read .claude/agents/templates/<name>.json. If not found, list available templates and abort. Use template's description prefix + remaining args as description. Store verifyCommand and commitFormat from the template.
   • --model <model>: one of haiku, sonnet, opus. Store for Agent tool's model parameter and registry. Falls back to CLAUDE_PLUGIN_OPTION_DEFAULT_MODEL env var if not specified.
   • --effort <level>: one of low, medium, high, max. Registry metadata only — the worker always runs at effort: high (set in its definition). This flag is stored for tracking/display purposes. Falls back to CLAUDE_PLUGIN_OPTION_DEFAULT_EFFORT env var if not specified.
   • --color <color>: one of red, blue, green, yellow, purple, orange, pink, cyan. Store in registry.
   • --max-turns <N>: positive integer. Registry metadata only — the worker always uses maxTurns: 200 (set in its definition). This flag is stored for tracking/display purposes.
   • Everything else (after removing flags) is the task description. If no flags matched, use full $ARGUMENTS as description. Set unspecified flags to null.
2. Generate ID, read registry.
3. TaskCreate with subject (60 chars max), description, activeForm (present continuous).
4. Add entry to registry: { id, taskId: null, description, status: "running", branch: null, commit: null, commitMessage: null, createdAt: <ISO now>, completedAt: null, filesChanged: [], notes: [], verifyCommand, commitFormat, model, effort, color, maxTurns }. Write registry.
5. Spawn Agent with subagent_type: "agent-manager:worker", and if model is set pass it via the Agent tool's model parameter. The prompt:

**Task:** {description} | **Agent ID:** {id}
{if verifyCommand}

**Verify command:** `{verifyCommand}`
{end}
{if commitFormat}

**Commit format:** `{commitFormat}`
{end}

**CRITICAL — after committing, write the result file to the ORIGINAL repo (not worktree):**

BRANCH=$(git rev-parse --abbrev-ref HEAD)
COMMIT=$(git rev-parse --short HEAD)
COMMIT_MSG=$(git log -1 --pretty=%s)
FILES=$(git diff {defaultBranch}..HEAD --name-only 2>/dev/null | tr '\n' ', ' | sed 's/,$//')
DIFF_STAT=$(git diff {defaultBranch}..HEAD --stat 2>/dev/null | tail -5)
COMMIT_LOG=$(git log {defaultBranch}..HEAD --oneline 2>/dev/null)
mkdir -p {repo_absolute_path}/.claude/agents
cat > {repo_absolute_path}/.claude/agents/{id}-result.txt << RESULT_EOF
branch: $BRANCH
commit: $COMMIT
commitMessage: $COMMIT_MSG
filesChanged: $FILES
summary: Completed task — {short description}
commitLog: $COMMIT_LOG
diffStat: $DIFF_STAT
RESULT_EOF

Template handling: Include {if ...} blocks only when the value is set. Remove {if}/{end} markers from the final prompt.

Note: The agent-manager:worker subagent already has background: true, isolation: worktree, and effort: high in its definition. The 5-phase execution process (Analyze, Plan, Implement, Verify, Commit) is in the worker's system prompt — do NOT duplicate it in the task prompt.

6. Update registry entry's taskId from the background Agent task (NOT TaskCreate). Write registry.
7. Tell user: agent <id> spawned. Show model/color if set. Available commands: list, switch, stop, merge, resume, retry, diff, logs, batch, note, watch, rebase, export, stats, history, clean.