I Built 'gwm': A CLI Tool to Streamline Git Worktree Operations

Since Claude Code was released, it seems more people have started using git worktree. I am one of them.
git worktree is very useful, but there are a few things that feel slightly inconvenient, and the commands can be hard to remember.
So, I created a CLI tool to make git worktree even more convenient.

https://github.com/shutootaki/gwm

Overview of Git Worktree

git worktree is a feature that allows you to create and use multiple independent working directories (worktrees) simultaneously for a single Git repository. This provides benefits such as:

• Reducing the hassle of stash/commit every time you switch branches
• Enabling parallel development/review by isolating directories per branch

Also, as a best practice for Claude Code, parallel development using Git worktree is recommended.

https://docs.anthropic.com/ja/docs/claude-code/common-workflows#git-worktreeで並列claude-codeセッションを実行する
https://www.anthropic.com/engineering/claude-code-best-practices

I often do code reviews in VSCode, so when I'm asked to review another branch during development, it tends to become a cycle of git stash and git checkout, and occasionally I accidentally lose history.
But if you use worktrees, you're invincible.

A Few Things Lacking in the Native git worktree Commands

• Adding a remote branch to a worktree is cumbersome
• Files listed in .gitignore are not copied when creating a worktree
• It's not an interactive CLI, so remembering commands is tedious
• You cannot open the editor directly after creating a worktree

Initially, I manually tweaked my .zshrc, but as the configuration grew, managing it became annoying, so I thought it would be easier to just create a CLI tool. That's how I ended up building my own.
Also, while sophisticated CLI tools like ccmanager already exist, I wanted to loosely couple the Cloud Code and worktree features, so I chose to implement my own.

Main Commands of gwm

Command	Main Use Case	Distinctive UI / Behavior
gwm add	Create a worktree and branch	Launches incremental search UI when run without arguments; allows entering the new branch name on the spot
gwm go	Move to or open a worktree in editor	Navigate to the selected worktree. Use --code / --cursor for IDE integration
gwm list	Display worktree list	Color-coded output for ACTIVE / MAIN / OTHER
gwm clean	Bulk delete unnecessary worktrees	Safely deletes only directories that are merged and unchanged
gwm pull-main	Update main worktree	Run git pull on main-like branches collectively
gwm help	Unified help	Displays global help and command-specific help hierarchically

Features

• Incremental search UI: Select branch names or worktrees via incremental search, minimizing typing.
• IDE integration options: Use --code or --cursor to launch an editor immediately after creation, saving time.
• Automatic .env file copy: If enabled in ~/.config/gwm/config.toml, .env* files are automatically duplicated when running gwm add.
• Safe cleanup: gwm clean checks merge status and local changes, proposing only removable worktrees.

Installation

# Global install
npm install -g @shutootaki/gwm

# or use npx (no installation needed)
npx @shutootaki/gwm

Basic Workflow

1. Create a Worktree

Create a New Worktree

Branch from the default branch and quickly build a worktree with the entered branch name. If you want to open it in VS Code or Cursor immediately after creation, simply add --code / --cursor.

gwm add

gwm add --code        # Open in VS Code
gwm add --cursor      # Open in Cursor
gwm add --cd          # Move to the directory

Create a Worktree from a Remote Branch

Fetch the remote branch and prepare a dedicated worktree for it. You can also launch an editor immediately with the options.

gwm add -r

gwm add -r --code        # Open in VS Code
gwm add -r --cursor      # Open in Cursor
gwm add -r --cd          # Move to the directory

2. Navigate to a Directory

Use the interactive UI to select the target worktree, then automatically cd into its directory or open it in an editor immediately.

gwm go               # Only cd or subshell

gwm go --code        # Open in VS Code
gwm go --cursor      # Open in Cursor

3. View the Worktree List

Display a list of worktrees associated with the current project, including their STATUS.

gwm list
gwm ls # alias

4. Delete Any Worktree

Safely delete a selected worktree through the interactive UI.

gwm remove
gwm rm # alias

5. Bulk Delete Unnecessary Worktrees

Scan and clean up worktrees that are already merged or deleted on the remote, and have no local changes.

gwm clean

For other detailed settings and options, please refer to the README.md below or run the gwm help <command> command.

https://github.com/shutootaki/gwm

Summary

Using gwm, you can consolidate worktree operations into a single command, significantly reducing the time and cognitive load associated with branch switching. If you find worktree management burdensome, give it a try!