task_retry — Claude Code subagent: retries and setup
The task_retry subagent for Claude Code restarts a task's agent after a failed launch. It reuses the existing tab when possible, or opens a new one.
MIT ★ 395 updated 2026-11-16
.claude/agents/task_retry.mdWhat task_retry does
task_retry makes another launch attempt when a task's agent fails to start. It uses the same tab if the agent's computer still holds it; otherwise, it opens a new tab. A launch that failed permanently is reopened there.
Each task gets at most three attempts, and the hub does not retry on its own. The subagent returns immediately; a separate message reports whether the agent started. It only handles tasks from the current conversation, and records the reason in the task history. Before retrying, task_start_keys must identify what stopped the launch.
What it helps with
- retry an agent after its launch fails
- reopen a task in a new tab after a permanent launch failure
- keep the retry reason in the task history
Example prompts for the agent
- Retry the agent for the task in the message; the connection stalled.
- Start the task's agent again because the launch error is fixed.
How to install task_retry
Manually: put the files in place
.claude/agents/task_retry.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/task_retry.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/task_retry.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 task_retry
How do I install task_retry in Claude Code?
Add the subagent file at .claude/agents/task_retry.md.
What does task_retry do?
It tries to start a task's agent again after a failed launch. It reuses the original tab if the agent's computer still holds it; otherwise, it opens a new tab.
How many times can task_retry retry a launch?
It allows up to three attempts per task. The hub does not initiate retries by itself.
Source text
task_retry.md · MIT
Start a task's agent again after it did not start: in the same tab while its computer keeps it (after task_start_keys answered what stopped it), otherwise in a new tab (a start that failed for good is reopened). At most 3 times per task; the hub never retries by itself. It returns at once; whether the agent came up arrives as a 督办 message. Only for a task of this conversation; your reason is kept with the task's history.
```json
{
"type": "object",
"required": ["todo_id", "reason"],
"properties": {
"todo_id": {
"type": "string",
"description": "the task's id, as the 督办 message gives it"
},
"reason": {
"type": "string",
"description": "why it should start now, in the user's language, one sentence"
}
}
}
```
© nwverse · MIT · nwverse/persona