Worktrees for Claude Development

task-plus manages git worktrees so you can run multiple Claude agents in parallel, each in its own isolated branch.

Quick Start

Task names are auto-prefixed with WT (e.g. add-login → WTadd-login, worktree dir my-app-WTadd-login).

# One-off: generate Taskfile snippets
task-plus wt --init

# Create a worktree and open VS Code in it
task-plus wt start add-login

# In the VS Code terminal, run claude interactively (with safety checks)
task-plus claude

# Or run a headless agent for the dashboard
task-plus wt agent add-login --spec="implement the login page"

# Monitor all running agents
task-plus wt dashboard          # web UI (default)
task-plus wt dashboard --term   # terminal table

Typical Workflow

  1. task-plus wt start add-login — creates a worktree and opens VS Code in it
  2. In the VS Code terminal: task-plus claude — verifies worktree sandbox is active (restricts access to ~/.ssh, ~/.aws, etc.), then runs claude --dangerously-skip-permissions
  3. Work interactively with Claude in the sandboxed worktree
  4. task-plus wt review add-login — review the diff
  5. task-plus wt merge add-login — merge and clean up

Or use the /c shorthand to create and clean up in one flow: task-plus wt start add-login /c

For headless/automated use, wt agent registers with the dashboard instead.

How It Works

flowchart TD
    A[wt start] --> B{Worktree exists?}
    B -->|No| C[git worktree add]
    B -->|Yes| D[Resume]
    C --> E[Write .claude/settings.json]
    D --> F{settings.json exists?}
    F -->|No| E
    F -->|Yes| G[Open VS Code]
    E --> G

flowchart TD
    A[wt agent] --> B{Worktree exists?}
    B -->|No| Z[Error: run wt start first]
    B -->|Yes| C[Start status server]
    C --> D[Register in agents.json]
    D --> E{--spec provided?}
    E -->|Yes| F[Run claude]
    E -->|No| G[Wait for Ctrl+C]
    F --> H[Deregister + shutdown]
    G --> H

Commands

Command Description
wt start NAME Create or resume a worktree, open VS Code
wt start NAME /c Shorthand: delegates to wt clean NAME
wt agent NAME [--spec="PROMPT"] Run Claude agent in worktree (registers with dashboard)
wt review NAME Show diff between main and the task branch
wt merge NAME Merge task branch into current branch, remove worktree
wt clean NAME Merge branch, close VS Code folder, remove from recent list, remove worktree, delete branch
wt list List all git worktrees
wt dashboard [--term] Live dashboard of running agents
wt --init Print Taskfile.yml snippets for all wt commands
claude Run claude --dangerously-skip-permissions (requires worktree + sandbox)

The claude Command

task-plus claude is a safety wrapper that:

  1. Checks you're in a git worktree (not the main checkout)
  2. Checks .claude/settings.json exists with sandbox enabled
  3. Runs claude --dangerously-skip-permissions

Any extra arguments are passed through to claude.

Agent Lifecycle

Each wt agent registers itself in ~/.config/task-plus/agents.json with:

  • HTTP port (random, serves /status)
  • PID, worktree path, branch, project name, start time

On exit (normal or Ctrl+C), the agent:

  1. Shuts down the HTTP status server
  2. Deregisters from agents.json

Stale entries (dead PIDs) are cleaned automatically on every wt agent.

Resume Support

If you run wt start add-login and the worktree directory already exists, it resumes instead of failing with "branch already exists". This handles:

  • Machine reboots
  • Interrupted sessions
  • Re-running a task after reviewing changes

Dashboard

The dashboard polls each registered agent's /status endpoint every 2 seconds.

Web mode (default, port 8091): Bulma-styled table with auto-refresh, powered by lofigui.

Terminal mode (--term): ANSI table that clears and redraws. Ctrl+C exits.

Both modes show: task key, branch, status (Running/Idle/Offline), last commit subject, uptime, and port.

Directory Layout

Worktrees are placed alongside the main repo (names include the WT prefix):

~/projects/
  my-app/              # main repo
  my-app-WTadd-login/  # worktree for task "add-login"
  my-app-WTfix-bug/    # worktree for task "fix-bug"

Each worktree gets a .claude/settings.json with sandbox config (denies ~/.ssh and ~/.aws reads). Sandbox stub files are excluded via .git/info/exclude.

Taskfile Integration

Run task-plus wt --init to get copy-paste Taskfile snippets. The task wt:* commands are Taskfile wrappers around task-plus wt *.

task wt:start TASK=my-feature
task wt:agent TASK=my-feature SPEC="implement the login page"
task wt:review TASK=my-feature
task wt:merge TASK=my-feature
task wt:clean TASK=my-feature
task wt:list
task wt:dashboard