Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ahmadawais/gwtree/llms.txt

Use this file to discover all available pages before exploring further.

​
General

GWTree is a git worktree manager designed for parallel development. It simplifies creating and managing multiple worktrees, making it perfect for running multiple AI coding agents (Claude Code, Command Code, Cursor) simultaneously on different features.
Git worktrees allow you to have multiple working directories attached to the same repository. Each worktree can have a different branch checked out, enabling you to work on multiple features in parallel without switching branches or stashing changes.Traditional workflow:
git stash
git checkout feature-a
# work on feature-a
git checkout main
git stash pop
With worktrees:
gwt feature-a  # Creates separate directory
cd ../repo-feature-a  # Work here independently
GWTree provides a streamlined interface over git’s native worktree commands:
  • Smart defaults: Automatically handles branch creation, naming, and directory structure
  • Interactive prompts: Guides you through worktree creation
  • Batch creation: Create multiple worktrees with one command
  • Status dashboard: See all worktrees’ status at a glance
  • Smart cleanup: Auto-remove merged worktrees
  • Merge helper: One command to merge, cleanup, and delete branches
  • Editor integration: Automatically opens worktrees in VS Code or Cursor
  • Dependency handling: Auto-installs dependencies in new worktrees
AI coding agents (Claude Code, Command Code, Cursor) work best when they have isolated environments:
  • No conflicts: Each agent works on its own branch
  • Parallel execution: Run multiple agents simultaneously
  • Clean merges: Merge each feature independently when ready
  • Instant setup: gwt a b c -x creates 3 worktrees in seconds
Example workflow:
gwt auth api dashboard -x  # Create 3 worktrees
# Claude Code → repo-auth/
# Command Code → repo-api/
# Cursor → repo-dashboard/

​
Installation & Setup

Install globally with npm:
npm install -g gwtree
Or with other package managers:
pnpm add -g gwtree
yarn global add gwtree
bun add -g gwtree
Verify installation:
gwt --version
  • Node.js: 18.0.0 or higher
  • Git: Any recent version
  • Operating System: Linux, macOS, Windows
Optional:
  • VS Code or Cursor (for editor integration)
  • pnpm/yarn/bun (for dependency management)
Configuration is stored in:
  • Config: ~/.config/gwtree/config.json
  • Worktree registry: ~/.gwtree/worktrees.json
Open config file:
gwt config
Reset to defaults:
gwt config reset

​
Usage

Several ways to create worktrees:Interactive mode:
gwt
Quick mode (single name for both worktree and branch):
gwt feature-login
Fast mode (skip all prompts):
gwt feature-login -y
Batch mode (create multiple at once):
gwt auth api dashboard
Batch + skip editor:
gwt a b c -x
Press ESC when prompted for “Worktree & branch name:” to enter separate names.Example:
  1. Run gwt
  2. Press ESC at the name prompt
  3. Enter worktree name: login-feature
  4. Enter branch name: feature/user-authentication
Result: Creates repo-login-feature/ directory with feature/user-authentication branch.
gwt ls
Shows all worktrees for the current repository with their paths and branch names.
gwt status  # or gwt st
Shows for each worktree:
  • Uncommitted changes
  • Commits ahead/behind main
  • Merge status
  • Added/deleted lines
Output example:
◆  feature-auth  +45 -12
└  ready to merge (3 commits ahead)

◆  feature-api  +128 -8
└  2 changed, 5 ahead

◆  feature-old
└  ✓ merged
Interactive removal:
gwt rm
Remove merged worktrees:
gwt clean
Remove all worktrees:
gwt clean --all
The merge command automates the entire merge workflow:
gwt merge feature-name
This command:
  1. Switches to main branch
  2. Merges the feature branch
  3. Removes the worktree
  4. Deletes the feature branch
The worktree must have no uncommitted changes to merge.

​
Configuration

Open config file:
gwt config
Set editor to one of:
  • "code" - VS Code (default)
  • "cursor" - Cursor
  • "default" - System default editor ($EDITOR)
  • "none" - Don’t open editor
Or skip editor for a single command:
gwt feature-name -x
Open config file:
gwt config
Set installDeps to false:
{
  "editor": "code",
  "installDeps": false,
  "lastPm": "pnpm"
}
GWTree detects your package manager by checking for lock files:
  1. pnpm-lock.yaml → pnpm
  2. bun.lockb → bun
  3. yarn.lock → yarn
  4. package-lock.json → npm
  5. package.json (no lock file) → pnpm
The detected package manager is saved in lastPm config and used for future worktrees.
The naming pattern is currently fixed as {repo}-{name}. For example:
  • Repository: my-app
  • Name: feature-login
  • Worktree directory: my-app-feature-login
To use different names, press ESC during creation and enter separate worktree and branch names.

​
Workflow

When creating a worktree, GWTree detects uncommitted changes and offers options:
  1. Stash changes: Saves changes with git stash (recommended)
  2. Ignore and continue: Leaves changes in current worktree
  3. Cancel: Aborts worktree creation
To skip prompts:
gwt feature-name -y  # Auto-stashes if needed
No. GWTree handles branch switching automatically:
  • If you’re not on main/master, it prompts to switch
  • In fast mode (-y), it switches automatically
  • Worktrees are always created from the main branch
If installDeps is enabled (default), GWTree:
  1. Detects package manager in the new worktree
  2. Runs install command (pnpm install, npm install, etc.)
  3. Shows install status in the output
Dependencies are installed independently in each worktree, so different worktrees can have different versions.
Yes! GWTree creates standard git worktrees. You can always use native git commands:
git worktree list
git worktree remove path/to/worktree
git worktree prune
GWTree is a convenience wrapper that makes worktree management easier.

​
Troubleshooting

If you delete a worktree directory manually, git keeps a stale reference.Solution:
git worktree prune
GWTree runs this automatically when creating worktrees.
gwt ls shows only worktrees created by GWTree. It reads from ~/.gwtree/worktrees.json.To see all worktrees (including manually created ones):
git worktree list
If you chose “Stash changes” when creating a worktree:
  1. Navigate to the original worktree (usually main repo)
  2. Apply the stash: 
    git stash pop
List all stashes:
git stash list

Build docs developers (and LLMs) love

Get started for freeTalk to us