103 lines
3.4 KiB
Markdown
103 lines
3.4 KiB
Markdown
---
|
|
name: worktree-task
|
|
description: 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
|
|
|
|
```bash
|
|
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/launch.py <branch-name> "<task-description>"
|
|
```
|
|
|
|
Example:
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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](https://github.com/ourines)
|