Worktrunk: Streamlining Git Worktree Management for AI Agent Workflows

Introduction

Worktrunk is a powerful command-line interface (CLI) tool, meticulously crafted in Rust, designed to revolutionize how developers manage Git worktrees. It has quickly become a popular Git worktree manager, particularly optimized for parallel AI agent workflows, such as Claude Code and Codex, making it easy to handle multiple development branches simultaneously. Worktrunk addresses the inherent complexities and clunky user experience of native Git worktrees, offering a robust solution for modern development practices.

Why Use Worktrunk and Key Benefits

Native Git worktrees, while powerful, can be cumbersome, especially when dealing with multiple parallel tasks or AI agent-driven development. Worktrunk simplifies this by providing a suite of intuitive commands and advanced features that transform worktree management into a seamless experience.

Key benefits and features include:

Simplified Core Commands: Worktrunk makes common worktree tasks effortless. Commands like wt switch, wt create, wt remove, and wt list abstract away the verbose native Git commands, making worktrees as easy to handle as branches.

Start with the core commands:

Core commands:

Switch worktrees:
- Worktrunk: wt switch feat
- Plain git: cd ../repo.feat

Create + start Claude:

Worktrunk: wt switch -c -x claude feat

Plain git:

git worktree add -b feat ../repo.feat && \
cd ../repo.feat && \
claude

Clean up:

Worktrunk: wt remove

Plain git:

cd ../repo && \
git worktree remove ../repo.feat && \
git branch -d feat

List with status:
- Worktrunk: wt list
- Plain git: git worktree list (paths only)

Workflow Automation: Expand into the more advanced commands as needed.

Workflow automation features:

Hooks - run commands on create, pre-merge, post-merge, etc.
LLM commit messages - generate commit messages from diffs.
Merge workflow - squash, rebase, merge, clean up in one command.
Interactive picker - browse worktrees with live diff and log previews.
Share build caches - ten worktrees get target/, node_modules/, etc without building or copying them (on APFS, btrfs, and XFS).
wt list --full - CI status and AI-generated summaries per branch.
PR checkout - wt switch pr:123 to jump straight to a PR's branch.
Dev server per worktree - hash_port template filter gives each worktree a unique port.
Aliases & per-branch variables - custom wt <name> commands and branch-scoped state for hook templates.
...and lots more.

Worktrunk is built to empower developers working with parallel AI agents, ensuring that managing multiple isolated development environments is no longer a bottleneck but a catalyst for productivity.

Installation

Worktrunk is easy to install across various platforms. Shell integration is recommended to allow commands to change directories.

Homebrew (macOS & Linux):

brew install worktrunk && wt config shell install

Cargo:

cargo install worktrunk && wt config shell install

Windows:

wt defaults to Windows Terminal's command, so Winget additionally installs Worktrunk as git-wt to avoid the conflict:

winget install max-sixty.worktrunk
git-wt config shell install

Alternatively, disable Windows Terminal's alias (Settings ? Apps ? Advanced app settings ? App execution aliases ? "Terminal"/"Terminal Preview") to use wt directly.

Arch Linux:

sudo pacman -S worktrunk && wt config shell install

Conda / Pixi (community-maintained feedstock):

conda install -c conda-forge worktrunk && wt config shell install

Or with Pixi: pixi global install worktrunk && wt config shell install.

Examples

Worktrunk simplifies common Git worktree operations. Here's a quick start guide:

Create a worktree for a new feature:

$ wt switch --create feature-auth
? Created branch feature-auth from main and worktree @ ~/repo.feature-auth

This command creates a new branch and worktree, then switches to it. After doing your work, you can check all worktrees with wt list:

$ wt list
  Branch        Status      HEAD±     main?    main…±    Remote?  Commit    Age  Message
@ feature-auth  +   ?      +27   -8   ?1       +31                4bc72dc    2h  Add authenticati…
^ main              ^?                                    ?1      0e631ad    1d  Initial commit

? Showing 2 worktrees, 1 with changes, 1 ahead, hidden: Path

The @ marks the current worktree. + means staged changes, ?1 means 1 commit ahead of main, ? means unpushed commits.

When done, you have two primary workflows:

PR workflow - commit, push, open a PR, merge via GitHub/GitLab, then clean up:

wt step commit                    # commit staged changes
gh pr create                      # or glab mr create
wt remove                         # after PR is merged

Local merge - squash, rebase onto main, fast-forward merge, clean up:

$ wt merge main
? Generating commit message and committing changes... (2 files, +53, no squashing needed)
  Add authentication module
? Committed changes @ a1b2c3d
? Merging 1 commit to main @ a1b2c3d (no rebase needed)
  * a1b2c3d Add authentication module
   auth.rs | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
   lib.rs  |  2 ++
   2 files changed, 53 insertions(+)
? Merged to main (1 commit, 2 files, +53)
? Removing feature-auth worktree & branch in background (same commit as main, _)
? Switched to worktree for main @ ~/repo

For parallel agents, create multiple worktrees and launch an agent in each:

wt switch -x claude -c feature-a -- 'Add user authentication'
wt switch -x claude -c feature-b -- 'Fix the pagination bug'
wt switch -x claude -c feature-c -- 'Write tests for the API'

The -x flag runs a command after switching; arguments after -- are passed to it. Configure post-start hooks to automate setup (install dependencies, start development servers).