Initial commit

commands/cleanup.md

@@ -0,0 +1,47 @@
+---
+description: Clean up a completed worktree task
+allowed-tools: Bash
+---
+
+# Cleanup Worktree Task
+
+Clean up a completed or abandoned worktree task by killing the tmux session and optionally removing the git worktree.
+
+## Usage
+
+Provide:
+1. **Session name** - The tmux session to clean up
+2. **--remove-worktree** (optional) - Also remove the git worktree directory
+
+## Example
+
+User: "Cleanup the my-feature worktree task"
+User: "Cleanup my-feature and remove the worktree"
+
+## Execution
+
+```bash
+# Kill session only (keep worktree for review)
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/cleanup.py <session-name>
+
+# Kill session AND remove worktree
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/cleanup.py <session-name> --remove-worktree
+```
+
+## What It Does
+
+1. Kills the tmux session
+2. Lists remaining git worktrees
+3. If `--remove-worktree`: removes the worktree directory
+4. Shows next steps (merge branch, create PR)
+
+## After Cleanup
+
+The branch still exists. To complete:
+- Merge: `git merge <branch-name>`
+- Create PR: `gh pr create --head <branch-name>`
+- Delete branch: `git branch -d <branch-name>`
+
+## Note
+
+Always review changes before removing the worktree. Use `/worktree:status` to check commits first.

commands/help.md

@@ -0,0 +1,69 @@
+---
+description: Show help for worktree-task plugin
+allowed-tools: ""
+---
+
+# Worktree Task Plugin Help
+
+A plugin for managing large coding tasks using git worktrees and background Claude Code sessions.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/worktree-task:launch <task>` | Launch a new background task in a separate worktree |
+| `/worktree-task:status [name]` | Check status of all or specific task |
+| `/worktree-task:resume <name>` | Resume an interrupted task |
+| `/worktree-task:cleanup <name>` | Clean up completed task and worktree |
+| `/worktree-task:merge <branch>` | Merge a feature branch into current branch |
+| `/worktree-task:rebase <branch>` | Rebase current branch onto a feature branch |
+| `/worktree-task:help` | Show this help message |
+
+## Quick Start
+
+```bash
+# 1. Launch a complex task in the background
+/worktree-task:launch "Implement user authentication with OAuth2"
+
+# 2. Check progress
+/worktree-task:status
+
+# 3. When done, merge the changes
+/worktree-task:merge feature-auth
+
+# 4. Clean up
+/worktree-task:cleanup feature-auth
+```
+
+## How It Works
+
+1. **Launch** creates a git worktree (isolated copy of your repo) and spawns a Claude Code instance in a tmux session
+2. **Monitor** via `/worktree-task:status` to see progress, logs, and completion state
+3. **Resume** if task gets interrupted (rate limits, API errors, network issues)
+4. **Merge/Rebase** with automatic conflict resolution powered by Claude
+5. **Cleanup** removes the tmux session and worktree when done
+
+## Best Practices
+
+- Use for tasks that take 10+ minutes or require extensive changes
+- Keep task descriptions clear and specific
+- Check status periodically to monitor progress
+- Use `--keep-worktree` with cleanup if you want to review changes first
+
+## File Locations
+
+- Worktrees: Created in parent directory of your repo (e.g., `../worktree-task-<name>`)
+- Task prompts: `/tmp/claude_task_prompt.txt` (temporary)
+- Monitor logs: `<plugin-dir>/.monitor_cron.log`
+
+## Requirements
+
+- macOS (for notifications)
+- tmux
+- git
+- Python 3.8+
+
+## Links
+
+- GitHub: https://github.com/ourines/worktree-task-plugin
+- Issues: https://github.com/ourines/worktree-task-plugin/issues

commands/launch.md

@@ -0,0 +1,42 @@
+---
+description: Launch a new background worktree task
+allowed-tools: Bash
+---
+
+# Launch Worktree Task
+
+Launch a background Claude Code session in a separate git worktree to execute a large task autonomously.
+
+## Usage
+
+Provide:
+
+1. **Branch name** - The git branch for this task (e.g., `feature/my-task`)
+2. **Task description** - What the background Claude should do
+
+## Example
+
+User: "Launch a worktree task on branch feature/auth to implement the authentication module"
+
+## Execution
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/launch.py "<branch-name>" "<task-description>"
+```
+
+## Prerequisites
+
+- Git working directory must be clean (commit or stash changes first)
+- tmux must be installed
+- Branch name will be created if it doesn't exist
+
+## What Happens
+
+1. Creates a git worktree at `../<project>-<branch-name>`
+2. Creates a tmux session named after the branch
+3. Launches Claude Code with `--dangerously-skip-permissions`
+4. Sends the task prompt with instructions to use Task tool for each phase
+
+## After Launch
+
+Use `/worktree:status` to monitor progress or `tmux attach -t <session>` to take over interactively.

commands/merge.md

@@ -0,0 +1,44 @@
+---
+description: Merge a feature branch into current branch
+allowed-tools: Bash
+---
+
+# Merge Feature Branch
+
+Merge a completed feature branch into the current branch using worktree + tmux with automatic conflict resolution.
+
+## Usage
+
+Provide the feature branch name to merge into the current branch.
+
+## Example
+
+User on `dev` branch: "Merge feature-auth into dev"
+User on `main` branch: "Merge feature/new-api into main"
+
+## Execution
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/merge.py "<feature-branch>"
+```
+
+## Prerequisites
+
+- Must be on the target branch (e.g., dev, main)
+- Feature branch must exist
+- tmux must be installed
+
+## What Happens
+
+1. Checks if feature branch has a worktree
+2. If worktree exists:
+   - Enters the worktree
+   - Rebases feature branch onto current branch
+   - Resolves any conflicts
+3. Returns to main repo
+4. Merges feature branch into current branch
+5. Resolves any merge conflicts using Claude Code in tmux
+
+## After Launch
+
+Use `tmux attach -t merge-<feature>-to-<target>` to monitor progress.

commands/rebase.md

@@ -0,0 +1,44 @@
+---
+description: Rebase current branch onto a feature branch
+allowed-tools: Bash
+---
+
+# Rebase onto Feature Branch
+
+Rebase the current branch onto a feature branch using worktree + tmux with automatic conflict resolution.
+
+## Usage
+
+Provide the feature branch name to rebase the current branch onto.
+
+## Example
+
+User on `dev` branch: "Rebase dev onto feature-auth"
+User on `main` branch: "Rebase main onto feature/new-api"
+
+## Execution
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/rebase.py "<feature-branch>"
+```
+
+## Prerequisites
+
+- Must be on the target branch (e.g., dev, main)
+- Feature branch must exist
+- tmux must be installed
+
+## What Happens
+
+1. Checks if feature branch has a worktree
+2. If worktree exists:
+   - Enters the worktree
+   - Rebases feature branch onto current branch
+   - Resolves any conflicts
+3. Returns to main repo
+4. Rebases current branch onto feature branch
+5. Resolves any rebase conflicts using Claude Code in tmux
+
+## After Launch
+
+Use `tmux attach -t rebase-<target>-onto-<feature>` to monitor progress.

commands/resume.md

@@ -0,0 +1,51 @@
+---
+description: Resume an interrupted worktree task
+allowed-tools: Bash
+---
+
+# Resume Worktree Task
+
+Resume a background worktree task that was interrupted (rate limit, API error, timeout, or waiting for input).
+
+## Usage
+
+Provide:
+1. **Session name** - The tmux session to resume
+2. **Message** (optional) - Custom instruction for Claude
+
+## Example
+
+User: "Resume the my-feature worktree task"
+User: "Resume my-feature with message 'Continue from phase 4'"
+
+## Execution
+
+```bash
+# Auto-detect error and send appropriate message
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/resume.py <session-name>
+
+# Send custom message
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/resume.py <session-name> "<message>"
+
+# Retry last failed operation
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/resume.py <session-name> --retry
+
+# Check status only (don't send message)
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/resume.py <session-name> --check
+```
+
+## Auto-Detection
+
+The script automatically detects:
+- `rate_limit` - Waits and sends resume message
+- `api_error` - Sends retry message
+- `timeout` - Sends retry message
+- `waiting_input` - Sends continue message
+
+## What It Does
+
+1. Checks if session exists
+2. Captures recent output to detect error type
+3. Generates appropriate resume message
+4. Sends message to Claude with Enter confirmation
+5. Shows response after brief wait

commands/status.md

@@ -0,0 +1,43 @@
+---
+description: Check status of worktree tasks
+allowed-tools: Bash
+---
+
+# Worktree Task Status
+
+Check the status of background worktree tasks.
+
+## Usage
+
+- Without arguments: List all active tmux sessions and git worktrees
+- With session name: Show detailed status for that session
+
+## Example
+
+User: "Check status of worktree tasks"
+User: "What's the status of the my-feature task?"
+
+## Execution
+
+```bash
+# List all tasks
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/status.py
+
+# Check specific task
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/status.py <session-name>
+```
+
+## Output Includes
+
+- Active tmux sessions
+- Git worktrees
+- Current branch and changed files
+- Recent commits
+- Last activity (tmux output)
+
+## Quick Actions
+
+After checking status, you can:
+- `/worktree:resume <session>` - Resume an interrupted task
+- `/worktree:cleanup <session>` - Clean up a completed task
+- `tmux attach -t <session>` - Take over interactively