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