How do I install the Worktree Task skill?

Run npx skillmds@latest add tomevault-io/worktree-task-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Worktree Task safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Worktree Task?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Worktree Task free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Worktree Task?

tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Worktree Task by tomevault-io — Agent Skill

Name: Worktree Task
Author: tomevault-io

Worktree Task

使用 git worktree + 背景代理会话管理大型任务（默认启动 Claude Code；可用 --codex 快速切到 Codex CLI，或通过 --agent-cmd 指定任意命令）。适合用户希望在不阻塞当前会话的情况下执行大型或多步骤任务。 Use when this capability is needed.

tomevault-io Updated Sep 17, 2026

File contents

Worktree Task Manager

This skill manages large coding tasks by spawning autonomous agent instances (默认 Claude Code，可选 --codex/--agent-cmd) in separate git worktrees via tmux sessions.

When to Use

User wants to execute a large task (>20 subtasks) without blocking current session
User mentions "background", "parallel", "worktree", or "autonomous" execution
Task involves creating a new service, major refactoring, or implementing complex features
User wants to continue other work while a large task runs

Available Commands

Use these slash commands for precise control:

Command	Description
`/worktree:launch`	Launch a new background task
`/worktree:status`	Check status of all or specific tasks
`/worktree:resume`	Resume an interrupted task
`/worktree:cleanup`	Clean up completed tasks

Core Workflow

1. Launch a Task

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/launch.py <branch-name> "<task-description>"

Example:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/launch.py feature/my-task "Execute the task: implement new feature. Read the tasks.md and implement all phases."

The script will:

Verify git status is clean (or prompt to commit/stash)
Create a git worktree with the specified branch
Create a tmux session
Launch Claude Code by default (use --codex for default Codex command or --agent-cmd to switch, e.g., codex --yolo -m gpt-5.1-codex-max -c model_reasoning_effort="high")
Send the task with instructions to use Task tool for each phase

2. Monitor Progress

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/status.py [session-name]

Without arguments, lists all active sessions. With a session name, shows detailed status.

3. Resume an Interrupted Task

If a task is interrupted (rate limit, API error, timeout):

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/resume.py <session-name> [message]

Options:

--retry - Retry the last failed task
--check - Only check status, don't send message

4. Cleanup

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/cleanup.py <session-name> [--remove-worktree]

Alerts

This plugin automatically sends macOS notifications when:

A background task completes successfully
A task encounters an error (rate limit, API error)
A session ends

Configure alerts in hooks/hooks.json.

Critical Instructions for Spawned Claude

The spawned agent receives these critical instructions:

MUST use Task tool - Each major phase must be executed via Task tool to prevent context overflow
Silent mode - No confirmations needed, user has pre-approved all operations
Complete execution - Do not stop until all tasks are done
Track with TodoWrite - Create and update todo list for visibility
Commit often - Make atomic commits after each logical unit

Notes

Worktrees are created in parent directory: ../<project>-<branch-name>
tmux session names have / and . replaced with -
Use tmux attach -t <session> to take over interactively
The spawned Claude runs with full permissions (--dangerously-skip-permissions)

💡 More Claude Code plugins: github.com/ourines

Converted and distributed by TomeVault — claim your Tome and manage your conversions.

---name: worktree-task-2description: 使用 git worktree + 背景代理会话管理大型任务（默认启动 Claude Code；可用 --codex 快速切到 Codex CLI，或通过 --agent-cmd 指定任意命令）。适合用户希望在不阻塞当前会话的情况下执行大型或多步骤任务。 Use when this capability is needed.---# Worktree Task ManagerThis skill manages large coding tasks by spawning autonomous agent instances (默认 Claude Code，可选 `--codex`/`--agent-cmd`) in separate git worktrees via tmux sessions.## When to Use- User wants to execute a large task (>20 subtasks) without blocking current session- User mentions "background", "parallel", "worktree", or "autonomous" execution- Task involves creating a new service, major refactoring, or implementing complex features- User wants to continue other work while a large task runs## Available CommandsUse these slash commands for precise control:| Command | Description ||---------|-------------|| `/worktree:launch` | Launch a new background task || `/worktree:status` | Check status of all or specific tasks || `/worktree:resume` | Resume an interrupted task || `/worktree:cleanup` | Clean up completed tasks |## Core Workflow### 1. Launch a Task```bashpython3 ${CLAUDE_PLUGIN_ROOT}/scripts/launch.py <branch-name> "<task-description>"```Example:```bashpython3 ${CLAUDE_PLUGIN_ROOT}/scripts/launch.py feature/my-task "Execute the task: implement new feature. Read the tasks.md and implement all phases."```The script will:1. Verify git status is clean (or prompt to commit/stash)2. Create a git worktree with the specified branch3. Create a tmux session4. Launch Claude Code by default (use `--codex` for default Codex command or `--agent-cmd` to switch, e.g., `codex --yolo -m gpt-5.1-codex-max -c model_reasoning_effort="high"`)5. Send the task with instructions to use Task tool for each phase### 2. Monitor Progress```bashpython3 ${CLAUDE_PLUGIN_ROOT}/scripts/status.py [session-name]```Without arguments, lists all active sessions. With a session name, shows detailed status.### 3. Resume an Interrupted TaskIf a task is interrupted (rate limit, API error, timeout):```bashpython3 ${CLAUDE_PLUGIN_ROOT}/scripts/resume.py <session-name> [message]```Options:- `--retry` - Retry the last failed task- `--check` - Only check status, don't send message### 4. Cleanup```bashpython3 ${CLAUDE_PLUGIN_ROOT}/scripts/cleanup.py <session-name> [--remove-worktree]```## AlertsThis plugin automatically sends macOS notifications when:- A background task completes successfully- A task encounters an error (rate limit, API error)- A session endsConfigure alerts in `hooks/hooks.json`.## Critical Instructions for Spawned ClaudeThe spawned agent receives these critical instructions:1. **MUST use Task tool** - Each major phase must be executed via `Task` tool to prevent context overflow2. **Silent mode** - No confirmations needed, user has pre-approved all operations3. **Complete execution** - Do not stop until all tasks are done4. **Track with TodoWrite** - Create and update todo list for visibility5. **Commit often** - Make atomic commits after each logical unit## Notes- Worktrees are created in parent directory: `../<project>-<branch-name>`- tmux session names have `/` and `.` replaced with `-`- Use `tmux attach -t <session>` to take over interactively- The spawned Claude runs with full permissions (`--dangerously-skip-permissions`)---> 💡 More Claude Code plugins: [github.com/ourines](https://github.com/ourines)---> Converted and distributed by [TomeVault](https://tomevault.io/claim/ourines) — claim your Tome and manage your conversions.

Frequently asked questions