Skip to main content
subagent CX Codex

agent_supervise — Claude Code subagent: task tracking and setup

The agent_supervise Claude Code subagent takes over an agent that was started without a task and tracks its work as a task in the current conversation. It routes progress messages to a supervisor and closes the task with task_review.

MIT ★ 395 updated 2026-11-16

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

What agent_supervise does

The subagent can adopt an agent opened by hand on the Agents page or launched with agent_start without a task. It creates a task in the current conversation, with optional completion checks and an expected duration. A long stretch without progress counts as stuck. The agent sends messages when it needs a review or answer, stops short, or reports its result.

By default, a background supervisor receives those messages and reviews the task; the main conversation can review it too. Set assistant.main_supervises_own_tasks to route the messages to the main conversation. If the agent already belongs to a task supervised by the current conversation, this subagent changes that task’s completion checks and expected duration, recording a scope change. task_scope is the tool for that edit. An agent attached to another conversation’s task stays there.

What it helps with

  • adopt an agent that was started without a task
  • track when an agent is waiting for review or an answer
  • set completion checks and an expected duration for an agent task
  • record a scope change on a task already under supervision

Example prompts for the agent

  • Take over the agent with session ID SESSION_ID on machine MACHINE and add its work as a task here.
  • Track the agent SESSION_ID with these completion checks and an expected duration in minutes.
  • Change the completion checks and expected duration for the task handled by agent SESSION_ID.

How to install agent_supervise

Manually: put the files in place

.claude/agents/agent_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 agent_supervise

How do I install agent_supervise in Claude Code?

Add the subagent file at .claude/agents/agent_supervise.md.

What does agent_supervise do?

It adopts an agent started without a task and tracks it as a task in the current conversation. The task is closed with task_review.

Who receives the supervisor messages?

By default, the background supervisor receives them and reviews the task. With assistant.main_supervises_own_tasks enabled, they go to the main conversation.

Source text

agent_supervise.md · MIT
Take an agent you did not hand out (opened by hand on the Agents page, or by agent_start without a task) under your supervision, from the main conversation, as if task_plan had started it: it becomes a task of this conversation (a todo, its card in the conversation) that is followed up: a 督办 message comes when it needs its supervisor (waits for review, stopped short, waits for an answer, makes no progress, reports), and task_review closes it. By default the background supervisor, the built-in conversation that follows up the tasks no leader supervises, gets those messages and reviews the task, and you may still review it yourself; with assistant.main_supervises_own_tasks on they come to you. The answer says which. On an agent of a task you supervise already, it sets that task's done_when and expect_minutes instead, as a logged scope change of the task's brief (the same rules as task_scope, which is the tool to use for it). An agent of another conversation's task stays that conversation's.

```json
{
  "type": "object",
  "required": ["machine", "session_id"],
  "properties": {
    "machine": {
      "type": "string",
      "description": "the machine's id or name, as agents_list shows it"
    },
    "session_id": {
      "type": "string",
      "description": "the agent's session id, or its first 8 characters"
    },
    "title": {
      "type": "string",
      "description": "the task in a short line (Chinese, under 20 characters); empty: the agent's title"
    },
    "done_when": {
      "type": "array",
      "maxItems": 6,
      "items": { "type": "string" },
      "description": "results you can check when it says it is done (a PR merged, a screenshot, what the live system answers)"
    },
    "expect_minutes": {
      "type": "integer",
      "description": "how long it should take from now; longer without progress counts as stuck"
    }
  }
}
```

© nwverse · MIT · nwverse/persona

Similar subagents

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

From the same set61

The whole set →
leader_progress The leader_progress Claude Code subagent adds direction updates to a work log. It reports completed goals and scheduled check-ins, rather than every intermediate step. CX Codex ★ 395repo stars interaction_answer The interaction_answer Claude Code subagent answers another agent’s question on the user’s behalf when the user has chosen an answer or delegated the choice. It picks from the offered options and leaves personal decisions to the user. CX Codex ★ 395repo stars agent_autoname_receipt The agent_autoname_receipt Claude Code subagent reads existing name-confirmation cards and one coding agent’s current naming snapshot. It helps inspect the available evidence about a rename. CX Codex ★ 395repo stars ask_escalate The ask_escalate Claude Code subagent routes decisions that task agents cannot make to the user. It groups unanswered task questions into one reminder. CX Codex ★ 395repo stars task_decided The task_decided Claude Code subagent records an owner's answer to a pending task decision. It captures the choice when the owner gives it in the conversation. CX Codex ★ 395repo stars 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

Project sponsors

Companies that keep this analytics open