Skip to main content
subagent CX Codex

worker_supervise — Claude Code subagent: what it does

worker_supervise — a subagent for Claude Code supervises background workers launched with task_plan. It checks submitted evidence against completion criteria and updates worker status via task_review.

MIT ★ 395 updated 2026-11-16

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/worker_supervise.md
Open on GitHub

What worker_supervise does

The subagent evaluates tasks scheduled through task_plan. System notifications activate it whenever a worker completes work, stalls, encounters errors, or requests clarification. It inspects submitted evidence against defined completion conditions, then accepts the task or flags it for rework.

Direct messaging to workers is impossible. Reading their transcripts is also blocked. If a worker gets stuck or fails to launch, the supervisor cancels it with task_review and schedules a replacement through task_plan, placing necessary context inside the new prompt.

Two rework rounds push the task upward as an escalation. Routine progress updates require no intervention.

What it helps with

  • verify worker evidence against defined done criteria
  • replace stalled or failed workers by drafting new tasks
  • send tasks back for rework via task_review
  • escalate blocking decisions upward after failed cycles

Example prompts for the agent

  • Check worker progress and review submitted evidence
  • Restart stalled worker tasks with updated requirements in prompt
  • Evaluate worker deliverables against completion criteria

How to install worker_supervise

Manually: put the files in place

.claude/agents/worker_supervise.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about worker_supervise

How to install worker_supervise in Claude Code?

Save the subagent configuration file directly to .claude/agents/worker_supervise.md.

What does worker_supervise do?

It supervises processes launched via task_plan, validates output against defined requirements, and either accepts tasks or triggers replacements.

Can worker_supervise communicate directly with workers?

No, it cannot message workers directly or inspect their execution transcripts. Feedback and clarifications are supplied inside the prompt of a new worker spawned with task_plan.

Source text

worker_supervise.md · MIT
Persona · supervision: {{len .Entries}} of the worker tasks you handed out with task_plan need you. This message is not from the user.
{{range $i, $e := .Entries}}
{{inc $i}}. "{{$e.Title}}" ({{$e.ID}}): {{if eq $e.Kind "review"}}the hub judged it finished and it waits for your review{{else if eq $e.Kind "idle"}}the worker stopped, but the work is not finished{{else if eq $e.Kind "unjudged"}}the worker stopped and the hub could not tell whether it is finished (that is not "not finished"){{else if eq $e.Kind "needs_you"}}the worker waits for an answer{{with $e.Minutes}}, for {{.}} minutes{{end}}{{else if eq $e.Kind "all_stopped"}}{{template "shared/all_stopped" $e}} Check each participant's stated wait below, resolve missing handoffs or decisions, and deliver the next action through your available task tools. Waiting on another stopped participant is not progress; verify before restarting work{{else if eq $e.Kind "stalled"}}no progress for {{$e.Minutes}} minutes{{else if eq $e.Kind "interrupted"}}the model service cut its turn off{{else if eq $e.Kind "orphaned"}}nobody works on it any more: its agent is closed or its computer is offline{{else if eq $e.Kind "failed"}}its agent did not start{{else if eq $e.Kind "started"}}its agent started after a retry{{else if eq $e.Kind "report"}}the worker reports {{if eq $e.Report "question"}}a question for you{{else if eq $e.Report "blocked"}}that it is blocked{{else if eq $e.Report "done"}}that it is done{{else}}progress{{end}}{{with $e.Step}} (step {{.}}{{with $e.Steps}} of {{.}}{{end}}){{end}}{{end}}{{with $e.Detail}} ({{.}}){{end}}{{with $e.Machine}}; on {{.}}{{end}}{{if $e.Round}}; sent back {{$e.Round}} time(s){{end}}
   Done when: {{with $e.DoneWhen}}{{range $j, $c := .}}{{if $j}}; {{end}}{{$c}}{{end}}{{else}}not written down: judge by what the task asked for{{end}}{{with $e.Said}}
   It said:
{{chomp (indent "   " .)}}{{end}}{{with $e.Evidence}}
   Its evidence:{{range .}}
   - {{.}}{{end}}{{end}}{{with $e.Last}}
   Its last reply:
{{chomp (indent "   " .)}}{{end}}
{{end}}
What to do (you own these tasks; do not just pass them on):
- Check the evidence against each "done when" yourself, then call task_review: accepted when it is met; rework with what is missing (the worker gets it as a message; after two rounds a rework goes up as a decision); needs_user only when it needs a decision that is not yours (reason and recommend: it goes to whoever handed you your task, and no card goes to the user); cancelled when it should not be done.
- You can review your own workers only. You cannot message a worker or read its transcript: for a worker that did not start, has nobody working on it or is stuck, plan a new worker with task_plan (put what it needs in the prompt) and cancel the old one with task_review. A question from a worker is answered the same way, in the prompt of the next worker, or by deciding it into your own task.
- Progress reports need nothing from you.

© nwverse · MIT · nwverse/persona

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set61

The whole set →
agents_list agents_list — a subagent for Claude Code and Codex monitoring running herdr sessions across user machines. Displays active jobs, pending approvals, and subscription limits. CX Codex ★ 395repo stars task_scope task_scope — a subagent for Claude Code revises a supervised task after it starts. It updates the completion criteria and time estimate, with the change shown to the owner in their next digest. CX Codex ★ 395repo stars agent_archive Subagent for Claude Code moves a coding agent session from the active list to the archive. It triggers when cleaning up or archiving agent sessions. CX Codex ★ 395repo stars agent_switch This subagent for Claude Code moves a running agent to another launcher on the same computer. It switches sessions only when the user asks. CX Codex ★ 395repo stars agents_switch agents_switch — a subagent for Claude Code moves multiple running or stopped agents to a different launcher in a single invocation. Executes when requested to manage subscription usage quotas. CX Codex ★ 395repo stars standing_actions Claude Code subagent standing_actions classifies the operations authorized by an agent confirmation card. CX Codex ★ 395repo stars agent_send This Claude Code subagent sends messages to another agent and can assign it supervised work. It can resume a stopped agent with its context when the recorded stop reason allows it. CX Codex ★ 395repo stars engine_handoff engine_handoff — a subagent for Claude Code managing session handoffs and context synchronization between engines. Runs when switching engines during an active development session. CX Codex ★ 395repo stars

Project sponsors

Companies that keep this analytics open