claude-worktree

A CLI tool that creates a git worktree and launches Claude Code with a prompt. With the -pane option, it opens in a new WezTerm or tmux pane, enabling parallel development across multiple worktrees.

Requirements

• Node.js (v22+)
• Git
• Claude Code
• WezTerm or tmux (optional, required only for -pane)
• GitHub CLI (optional, enables PR info display in clean)

Installation

npm install -g @hytfjwr/claude-worktree

Or run directly with npx:

npx @hytfjwr/claude-worktree feature/auth 'Implement authentication feature'

Quick Start

# Create a worktree and start Claude Code
claude-worktree feature/auth 'Implement authentication feature'

# Open in a new pane for parallel development (WezTerm or tmux)
claude-worktree feature/auth 'Implement authentication feature' -pane

# Resume a session in an existing worktree
claude-worktree resume feature/auth

Usage

Create Command

claude-worktree <branch-name> <prompt>
claude-worktree <branch-name> -plan <file-path>

List Command

claude-worktree list [options]

Resume Command

claude-worktree resume [<branch-name>] [<prompt>]

Clean Command

claude-worktree clean [options]

Help / Version

claude-worktree -h
claude-worktree -help
claude-worktree -version
claude-worktree --version

Typo Suggestions

Mistyped options, commands and branch names are matched against the known ones by Levenshtein distance, and the closest candidate is suggested:

$ claude-worktree list -jsom
Unknown option for list command: "-jsom" (did you mean "-json"?)

$ claude-worktree lst
Missing prompt for branch "lst".
...
Did you mean the "list" command?

$ claude-worktree resume feature/aut
Worktree not found for branch: feature/aut

Did you mean "feature/auth"?

Options

• -p, -pane - Open in a new pane (requires WezTerm or tmux; default: run in current terminal)
• -plan <file> - Read prompt from a file (cannot be used with inline prompt)
• -b, -base <branch> - Specify base branch (default: current branch)
• -d, -danger - Skip workspace warning (uses --dangerously-skip-permissions)
• -merge - Auto-merge into base branch and cleanup after task completion
• -draft - Auto-create Draft PR after task completion (cannot be used with -merge or -pr)
• -pr - Auto-create PR after task completion (cannot be used with -merge or -draft)
• -pull - Fetch latest base branch from remote before creating worktree
• -n, -dry-run - Preview what would be created without executing
• -v, -verbose - Show hook execution logs
• -h, -help - Show help
• -version, --version - Show version number

List Options

• -j, -json - Output as JSON
• -no-status - Hide Claude session status (shown by default)
• -fetch - Fetch from remote before listing (default: local only; with -watch, only the first refresh fetches)
• -w, -watch - Redraw the list on an interval until you quit (requires a TTY; cannot be used with -json)
• -interval <seconds> - Refresh interval for -watch (default: 2, min: 1, max: 60)
• -q, -quiet - Suppress informational output (errors only)
• -v, -verbose - Show full paths and details

In -watch mode the list is redrawn in the terminal's alternate screen buffer, so it never pollutes the scrollback:

• r — refresh immediately
• q / Esc / Ctrl+C — quit

-fetch is applied only to the first refresh, so a long watch session does not keep hitting the remote.

When resume or clean -all is run without a branch name, an interactive TUI selector is displayed:

• ↑/↓ or j/k — navigate items
• Enter — confirm selection
• Space — toggle item (multi-select only)
• a — select/deselect all (multi-select only)
• q/Esc — cancel

When stdin is not a TTY (e.g., piped input), the selector falls back to a numbered-list prompt.

Resume Options

• -p, -pane - Open in a new pane (requires WezTerm or tmux; default: run in current terminal)
• -d, -danger - Skip workspace warning (uses --dangerously-skip-permissions)
• -v, -verbose - Show verbose output

Clean Options

• -f, -force - Skip confirmation prompt
• -a, -all - Show all worktrees for manual selection
• -n, -dry-run - Preview targets without deleting
• -v, -verbose - Show hook execution logs

Examples

# Create a worktree and start Claude Code in current terminal
claude-worktree feature/auth 'Implement authentication feature'

# Open in a new pane (WezTerm or tmux)
claude-worktree feature/auth 'Implement authentication feature' -pane

# Short form
claude-worktree fix/bug-123 'Fix login bug' -p

# Read prompt from a plan file
claude-worktree feature/api -plan ./plan.md

# Create worktree from specific base branch
claude-worktree feature/auth 'Implement authentication feature' -base develop

# Skip workspace warning
claude-worktree feature/auth 'Implement authentication feature' -danger

# Auto-merge into base branch after task completion
claude-worktree feature/auth 'Implement authentication feature' -merge

# Auto-create Draft PR after task completion
claude-worktree feature/auth 'Implement authentication feature' -draft

# Draft PR with specific base branch
claude-worktree feature/auth 'Implement authentication feature' -draft -base main

# Auto-create PR after task completion
claude-worktree feature/auth 'Implement authentication feature' -pr

# PR with specific base branch
claude-worktree feature/auth 'Implement authentication feature' -pr -base main

# Fetch latest remote before creating worktree
claude-worktree feature/auth 'Implement authentication feature' -pull

# Fetch latest remote with specific base branch
claude-worktree feature/auth 'Implement authentication feature' -pull -base main

# Resume a Claude session in an existing worktree
claude-worktree resume feature/auth

# Resume with an additional prompt
claude-worktree resume feature/auth 'Continue the authentication implementation'

# Interactive worktree selection (arrow-key TUI)
claude-worktree resume

# List worktrees with status
claude-worktree list

# Hide Claude session status
claude-worktree list -no-status

# Live view: redraw the list every 2 seconds until you quit
claude-worktree list -watch

# Live view with a 5 second interval
claude-worktree list -watch -interval 5

# List worktrees as JSON
claude-worktree list -json

# Clean up unnecessary worktrees
claude-worktree clean

# Preview worktrees to be deleted
claude-worktree clean -dry-run

# Select from all worktrees manually (arrow-key TUI)
claude-worktree clean -all

# Preview what would be created (dry-run)
claude-worktree feature/auth 'Implement authentication feature' -dry-run

JSON Output Schema

When using claude-worktree list -json, the output follows this schema:

{
  "worktrees": [
    {
      "path": "/absolute/path/to/worktree",
      "branch": "feature/auth",
      "isMain": false,
      "isLocked": false,
      "isDirty": false,
      "status": "Active",
      "commit": {
        "hash": "abc1234",
        "message": "Commit message",
        "date": "2025-01-15T10:00:00.000Z"
      },
      "aheadBehind": { "ahead": 2, "behind": 0 },
      "session": {
        "status": "running",
        "elapsedMs": 900000,
        "mode": "pane",
        "paneId": 3
      }
    }
  ]
}

| Field | Type | Description | |---|---|---| | path | string | Absolute path to the worktree directory | | branch | string \| null | Branch name, or null for detached HEAD | | isMain | boolean | Whether this is the main worktree | | isLocked | boolean | Whether the worktree is locked | | isDirty | boolean | Whether the worktree has uncommitted changes | | status | string | One of: "Main", "Locked", "Merged", "Dirty", "Active" | | commit | object \| null | Latest commit info (hash, message, date) | | aheadBehind | object \| null | { ahead: number, behind: number } relative to main branch | | session | object \| undefined | Claude session info (only with -status flag) | | session.status | string | "running" or "done" | | session.elapsedMs | number | Milliseconds since session started | | session.mode | string | "pane" or "terminal" | | session.paneId | number \| string \| undefined | Pane ID — WezTerm (number) or tmux (string, e.g. %0). Pane mode only. |

Hook Configuration

You can define project-specific hooks in .claude-worktree.json at the repository root:

{
  "maxWorktrees": 5,
  "hookTimeout": 600,
  "postCreate": "cd {path} && docker-compose -p app-{slot} up -d",
  "postCreateTimeout": 300,
  "preClean": "cd {path} && docker-compose down",
  "preCleanTimeout": 120,
  "postClean": "docker volume rm app-{path}-data || true",
  "postCleanTimeout": 60
}

Worktree Limit

• maxWorktrees — Maximum number of concurrent worktrees (excludes main). If set, blocks creation when the limit is reached.

Template Variables

• {path} — worktree path
• {slot} — auto-assigned slot number (1-9) based on port availability (8881-8889). Slot assignments are persisted to ~/.cache/claude-worktree/slots.json so that preClean/postClean hooks can reference the same slot that was assigned during postCreate.

Hooks

• postCreate — Runs after worktree creation (e.g., start Docker containers). If the hook fails, the worktree is automatically rolled back.
• preClean — Runs before worktree deletion (e.g., stop Docker containers). If the hook fails, deletion continues with a warning.
• postClean — Runs after worktree and branch deletion (e.g., Docker volume removal, DNS cleanup). If the hook fails, the operation continues with a warning.

Timeout

• hookTimeout — Global default timeout in seconds (default: 600)
• postCreateTimeout — Override timeout for postCreate hook
• preCleanTimeout — Override timeout for preClean hook
• postCleanTimeout — Override timeout for postClean hook

Priority: hook-specific value > hookTimeout > default (600s)

Environment Variables

• CLAUDE_WORKTREE_CACHE_DIR — Override the slot cache directory (default: ~/.cache/claude-worktree)
• CLAUDE_WORKTREE_NO_MOUSE — Disable mouse support in the interactive selectors (any non-empty value). Mouse tracking takes over the terminal's own text selection while a selector is open, so set this if you need to copy from the list.
• NO_COLOR — Disable colored output (no-color.org). Colors are also automatically disabled when stdout is not a TTY (e.g., piped output).

License

MIT