gh-ourines-worktree-task-plugin/skills/worktree-task/SKILL.md

name, description

name	description
worktree-task	Manage large coding tasks using git worktrees and background Claude Code sessions. Use this when users want to execute large, complex tasks (like implementing a new service, major refactoring, or multi-step features) in isolation without blocking the current session. Spawns autonomous Claude Code instances via tmux.

Worktree Task Manager

This skill manages large coding tasks by spawning autonomous Claude Code instances 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:

1. Verify git status is clean (or prompt to commit/stash)
2. Create a git worktree with the specified branch
3. Create a tmux session
4. Launch Claude Code with --dangerously-skip-permissions
5. 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 Claude Code instance receives these critical instructions:

1. MUST use Task tool - Each major phase must be executed via Task tool to prevent context overflow
2. Silent mode - No confirmations needed, user has pre-approved all operations
3. Complete execution - Do not stop until all tasks are done
4. Track with TodoWrite - Create and update todo list for visibility
5. 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