git-worktree-toolbox

Git Worktree Toolbox

🌳 Git Worktree Toolbox is a MCP server and CLI for managing git worktrees.

Create isolated workspaces without the hassle of stashing changes and switching branches.

Ideal for AI-assisted development workflows requiring multiple features in parallel.

As a backup, use the gwtree command to run any of the mcp tools yourself.

Available MCP Tools (10)

• list - List projects and their worktrees
• new - Create a new worktree with a matching branch
• archive - Archive worktrees and branches
• go - Open worktree folder in your editor
• changes - Review changes and optionally commit and push
• grab - Pull in changes from a specific worktree
• pr - Generate a link to create a pull/merge request
• prompt - Resume AI agent sessions or setup AI agent auto-prompt (Claude/Cursor)
• doctor - Fix worktree metadata issues
• clean - Archive unused worktrees

Usage Examples

Once the MCP server is added, here's how you might phrase requests to activate each tool:

• List worktrees: "List worktrees", "Show me all my projects and worktrees", "What worktrees do I have?"
• Create new worktree: "New worktree for fixing the login bug", "Set up a new workspace for the user dashboard feature", "Make a worktree for the API refactor"
• Archive worktree: "Archive this worktree", "Clean up the completed feature worktree", "Remove the old worktree and its branch"
• Open worktree: "Open the login bug worktree in my editor", "Switch to the dashboard worktree", "Go to the API refactor workspace"
• Review/Push changes: "Show changes from task-245", "What files have I modified?", "Push changes for task-245"
• Grab changes: "Get login bug worktree changes", "Merge updates from the dashboard branch", "Pull in changes from the API worktree"
• Create PR: "Generate a pull request link", "Create a merge request for task-245", "Make a PR for the current changes"
• AI agent prompt: "Resume Claude session for task-245", "Setup Claude auto-prompt", "Setup Cursor Agent", "Continue conversation in this worktree"
• Fix issues: "Fix my worktree metadata", "Repair worktree configuration", "Doctor the worktree setup"
• Clean up: "Clean unused worktrees", "Archive old worktrees", "Remove completed worktrees"

Get Started

Add the MCP Server to Cursor / Claude Desktop:

{
  "mcpServers": {
    "git-worktree-toolbox": {
      "command": "npx",
      "args": ["-y", "git-worktree-toolbox@latest"]
    }
  }
}

The gwtree CLI is also available after a global installation:

npm install -g git-worktree-toolbox

Run gwtree help to see the available tools and their flags.

CLI commands

# List all projects with worktrees
gwtree list

# Create a new worktree with a matching branch
gwtree new "Fix login bug and flow"

# Archive current worktree (with branch removal)
gwtree archive -r

# Open current worktree and branch in editor
gwtree go

# Show the changes from all associated worktrees
gwtree changes

# Pull in changes from a specific worktree
gwtree grab fix-login-bug-1242

# Commit and push changes in a specific worktree
gwtree changes fix-login-bug-1242 -c

# Generate a link to create a pull/merge request
gwtree pr

# Fix worktree metadata issues
gwtree doctor

# Archive unused worktrees
gwtree clean

# Setup AI agent auto-prompt plugin (Claude by default)
gwtree prompt setup

# Setup with Cursor Agent instead
gwtree prompt setup --cursor

# Resume AI agent session for a worktree
gwtree prompt <worktree-id>

# Show help with advanced flag usage examples
gwtree help

AI Agent Prompt Plugin

When using the CLI, an interactive session with either Claude CLI or Cursor Agent can be automatically spawned in the new workspace, ready to use.

Quick Start

# 1. Setup AI agent plugin (one-time)
gwtree prompt setup              # Claude (default)
gwtree prompt setup --cursor     # Cursor Agent

# 2. Create worktree - AI agent auto-launches
gwtree new "Add user authentication"
# → AI agent starts with task context
# → Session ID saved in worktree metadata

# 3. Resume AI agent session later
gwtree prompt user-authentication-123
# → Continue conversation with full history

Features

• Auto-launch: AI agent starts automatically with task context
• Session persistence: Each worktree gets a unique session
• Resume capability: Continue conversations anytime with gwtree prompt
• Customizable prompts: Edit ~/.gwtree/ai-agent.yaml to customize templates
• Switchable providers: Switch between Claude CLI and Cursor Agent
• Optional: Disable globally or per-worktree

See src/plugins/claude-prompt/README.md and src/plugins/cursor-agent/ for more information.

Configuration

Optionally, configure the worktrees folder and project directories using environment variables:

# Storage directory for worktrees
# Default: ~/.gwtree/worktrees
export BASE_WORKTREES_PATH=~/my-custom-worktrees

# Custom project directories for discovery (colon-separated)
# Default: ~/Projects, ~/Code, ~/Developer
export PROJECT_DIRECTORIES="$HOME/custom-projects:$HOME/work"

Add these to your shell profile (~/.zshrc, ~/.bashrc, etc.) to persist across sessions.