Worktree Task Plugin

Worktree Task Plugin

Manage large coding tasks using git worktrees and background agent sessions. Spawns autonomous Claude Code or Codex instances that run independently, freeing your main session.

Features

- Launch: Spawn autonomous agent instances in separate git worktrees
  - Default: Claude Code (claude --dangerously-skip-permissions)
  - --codex: Quick switch to Codex CLI
  - --agent-cmd: Custom agent command
- Auto-Recovery: Background monitor automatically detects and recovers from errors (rate limits, API errors, timeouts)
- Status: Monitor running tasks and their progress
- Resume: Manually recover interrupted tasks
- Cleanup: Remove completed tasks and worktrees
- Merge/Rebase: Automatic conflict resolution powered by Claude
- Alerts: macOS notifications when tasks complete or fail
- Auto-Update: Notifies when plugin updates are available

Usage

Via Commands (recommended)

Via Skill (automatic)

Claude will automatically use this skill when you mention:
- "Run this in background"
- "Execute in a worktree"
- "Spawn a separate task"
- Large, complex implementations

Structure

How It Works

1. Launch: Creates a git worktree, starts a tmux session, runs the agent with task prompt
2. Auto-Recovery: Background monitor polls for errors and automatically resumes (rate limits, API errors, timeouts)
3. Monitor: Check progress via /worktree-task:status
4. Alert: macOS notifications via osascript on completion/failure
5. Cleanup: Kills tmux session, stops monitor, removes worktree
6. Merge/Rebase: Uses Claude in tmux to automatically resolve conflicts

Configuration

Tasks are tracked via tmux sessions and git worktrees - no separate database needed.

- Worktrees: Created in parent directory (e.g., ../worktree-task-)
- Monitor logs: .monitor_cron.log in plugin…