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
.claude/agents/agent_supervise.mdWhat 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_IDon machineMACHINEand add its work as a task here. - Track the agent
SESSION_IDwith 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.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/agent_supervise.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/agent_supervise.mdCursor also reads .claude/agents/
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