Quickstart

Get your first worktree running in minutes with practical examples

Create your first worktree

Navigate to any git repository and create a worktree:

1. Interactive mode

   Run gwt without arguments for an interactive prompt:

   gwt
   

   You’ll be guided through:

   1. Name — Enter name for both worktree and branch (press ESC to set separately)
   2. Stash/Switch — Handle uncommitted changes and switch to main
   3. Pull — Fetch latest changes from remote

   Press ESC during name input to set worktree and branch names separately.

2. Quick mode

   Pass a name directly to skip prompts:

   gwt feature-login
   

   This creates:

   • Worktree: repo-feature-login/
   • Branch: feature-login

   The CLI shows each command as it runs:

   │
   │  ◆  Prune  git worktree prune
   │  └  removes stale refs
   │
   │  ◆  Create  git worktree add -b "feature-login" .../repo-feature-login "main"
   │  └  /Users/you/projects/repo-feature-login
   │
   │  ◆  Install  pnpm install
   │  └  installs dependencies
   │
   │  ◆  Open  code .../repo-feature-login
   │  └  opens in editor
   │
   └  Done  cd ../repo-feature-login
   
3. Navigate to worktree

   Change to your new worktree directory:

   cd ../repo-feature-login
   

   Your editor should already be open with the new worktree.

Multi-agent parallel development

The real power of GWTree is creating multiple worktrees for parallel AI agent development:

# Create 3 worktrees instantly
gwt auth api dashboard -x

This creates three isolated worktrees:

Worktree 1: auth

repo-auth/
└── branch: auth

The -x flag (or --no-editor) skips opening editors — perfect for batch creation.

Now run different AI agents in each worktree:

• Claude Code in repo-auth/
• Command Code in repo-api/
• Cursor in repo-dashboard/

Fast mode with defaults

Skip all prompts using your saved config:

gwt feature-login -y

The -y or --yes flag uses saved defaults for stash, pull, and editor preferences.

List worktrees

See all worktrees for the current repo:

gwt ls
# or
gwt list

Output:

╔═╗╦ ╦╔╦╗
║ ╦║║║ ║
╚═╝╚╩╝ ╩

Worktrees for repo
│
│  ◆  auth
│  └  /Users/you/projects/repo-auth
│
│  ◆  api
│  └  /Users/you/projects/repo-api
│
│  ◆  dashboard
│  └  /Users/you/projects/repo-dashboard
│
└  3 worktrees

Check status

See the status of all worktrees:

gwt status
# or
gwt st

Shows for each worktree:

• Changed files
• Commits ahead/behind main
• Merge readiness
• Line additions/deletions

Status for repo
│
│  ◆  auth  +127 -43
│  └  2 changed, 3 ahead
│
│  ◆  api  +89 -12
│  └  ready to merge (2 commits ahead)
│
│  ◆  dashboard
│  └  ✓ merged
│
└  1 ready to merge, 1 in progress, 1 merged

Merge and cleanup

When a feature is complete, merge it back to main:

gwt merge api

This automatically:

1. Switches to main branch
2. Merges the feature branch
3. Removes the worktree
4. Deletes the branch

Make sure all changes are committed before merging. The command will fail if there are uncommitted changes.

Clean merged worktrees

Remove all worktrees that have been merged to main:

gwt clean
# or
gwt c

Remove all worktrees (merged or not):

gwt clean --all
# or
gwt c -a

Remove specific worktrees

Interactive search and remove:

gwt rm
# or
gwt remove

Use fuzzy search to find and remove worktrees:

? Search worktree: › api

  ❯ api repo-api
    /Users/you/projects/repo-api

? Remove repo-api? › (Y/n)

Essential commands

Command	Description
gwt	Create worktree (interactive)
gwt <name>	Quick create with name
gwt a b c	Batch create multiple
gwt <name> -y	Fast mode, skip prompts
gwt <name> -x	Skip opening editor
gwt ls	List all worktrees
gwt status	Show status dashboard
gwt merge <name>	Merge and cleanup
gwt clean	Remove merged worktrees
gwt rm	Interactive remove
gwt config	Open config file

Package manager detection

GWTree automatically detects your package manager:

• pnpm-lock.yaml → uses pnpm install
• bun.lockb → uses bun install
• yarn.lock → uses yarn install
• package-lock.json → uses npm install
• package.json only → defaults to pnpm install

Set installDeps: false in config to disable automatic dependency installation.

What’s next?

You’re ready to use GWTree for parallel AI agent development! Here are some tips:

Workflow tip

Use gwt status frequently to track progress across all worktrees

Clean habit

Run gwt clean regularly to remove merged worktrees

Fast creation

Use -x flag for batch creation: gwt a b c -x

Configuration

Customize editor and install preferences with gwt config