Worktree CLI

Git worktree management for AI coding assistants. Enables parallel development across multiple branches without context switching.

Why?

AI coding assistants work best with isolated contexts. Git worktrees give each task its own directory—no stashing, no branch switching, no conflicts. Your AI can work on a feature while you review a PR in another worktree.

Quick Start

# Install
npm install -g @fnebenfuehr/worktree-cli

# Convert existing repo to worktree structure
cd your-project && worktree setup

# Create a feature worktree
worktree create feat/new-feature

See docs/QUICKSTART.md for detailed setup guide.

MCP Integration

Add to your Claude Code or AI assistant config:

{
  "mcpServers": {
    "worktree": {
      "command": "npx",
      "args": ["-y", "@fnebenfuehr/worktree-cli", "mcp"]
    }
  }
}

Your AI assistant can now:

• Check worktree status before modifications
• Create isolated worktrees for features/fixes
• Switch between work contexts
• Checkout PRs for review
• Clean up merged branches

MCP Tools

| Tool | Description | |------|-------------| | worktree_status | Check if repo uses worktrees, current branch, default branch | | worktree_list | List all worktrees with branches and paths | | worktree_create | Create new worktree with branch | | worktree_checkout | Intelligent checkout: switch/create from local/remote | | worktree_pr | Checkout GitHub PR by number or URL | | worktree_switch | Switch to existing worktree | | worktree_remove | Remove worktree (with merge safety checks) | | worktree_setup | Convert repo to worktree structure |

CLI Commands

| Command | Description | |---------|-------------| | worktree clone <url> | Clone repo into worktree-ready structure | | worktree setup | Convert existing repo to worktrees | | worktree create <branch> | Create worktree and branch | | worktree checkout <branch> | Smart checkout: switch or create from local/remote | | worktree pr <number\|url> | Checkout PR branch | | worktree switch [branch] | Switch to worktree (interactive if no branch) | | worktree list | List all worktrees | | worktree remove <branch> | Remove worktree | | worktree update | Update CLI to latest version |

Configuration

Create .worktree.json in your repo root (auto-generated by setup/clone):

{
  "defaultBranch": "main",
  "post_create": ["npm install"],
  "pre_remove": ["docker compose down"],
  "copy_files": [".env", ".env.local"]
}

| Option | Description | |--------|-------------| | defaultBranch | Base branch for new worktrees | | post_create | Commands to run after creating worktree | | pre_remove | Commands to run before removing worktree | | post_remove | Commands to run after removing worktree | | copy_files | Files to copy from main worktree |

Hooks receive environment variables: WORKTREE_PATH, WORKTREE_BRANCH, WORKTREE_MAIN_PATH.

Comparison

| Task | Manual Git | Worktree CLI | |------|------------|--------------| | Create feature branch | git worktree add -b feat/x ../feat-x origin/main | worktree create feat/x | | Switch context | cd ../other-worktree | worktree switch other | | Setup new repo | Multiple commands + directory management | worktree clone <url> | | Post-create setup | Manual: install deps, copy .env | Automatic via hooks | | PR review | Stash → checkout → review → checkout → pop | worktree pr 123 | | AI integration | Manual git commands | Native MCP server |

Directory Structure

After setup, your repo looks like:

project/
├── main/           # default branch worktree
├── feat-auth/      # feature worktree
└── fix-bug/        # bugfix worktree

Each directory is a complete working copy with shared git history.

Documentation

• Quick Start Guide
• AI Coding Workflows
• Hooks Configuration

License

MIT

Links

• Issues
• Discussions