Worktrunk: git worktree management for AI agent workflows
/worktrunk
Worktrunk is worth installing the moment you're running even one AI agent in parallel with other work. Native git worktree commands require typing a branch name three times just to create one worktree; Worktrunk reduces the common cases to a single command. The catch is that shell integration is effectively required for the full experience, and the copy-on-write build cache only works on APFS, btrfs, and XFS, leaving ext4 users without that particular benefit.
What is Worktrunk
Worktrunk is a Rust CLI that wraps git worktree operations into developer-friendly commands. It computes worktree paths from branch names using a configurable template, provides a status-rich list view showing ahead/behind counts and commit messages, and integrates with the shell so switching worktrees also changes directories. The README describes it as designed specifically for parallel AI agent workflows, letting multiple Claude Code or Codex instances each work in an isolated directory without conflicts.
Core commands and capabilities
- โ`wt switch` creates or navigates to worktrees by branch name; paths are computed automatically
- โ`wt list` shows all worktrees with status, staged changes, ahead/behind counts, and commit messages
- โ`wt remove` deletes a worktree and optionally its associated branch
- โ`wt merge` squashes, rebases onto a target branch, and cleans up the worktree in one command
- โ`wt step` automates the commit-push lifecycle with LLM-generated commit messages
- โHooks run custom commands on worktree creation, pre-merge, post-merge, and other lifecycle events
- โCopy-on-write shared build caches avoid rebuilding `target/` and `node_modules/` across worktrees
- โInteractive picker with streaming CI status and diff/PR previews for browsing worktrees visually
When to reach for Worktrunk
- โขRunning multiple AI agents in parallel, each in its own worktree, without agents overwriting each other's changes
- โขManaging several feature branches simultaneously without checkout switching overhead
- โขSharing compiled artifacts across worktrees on APFS, btrfs, or XFS filesystems to skip rebuilds
- โขAutomating development environment setup with hooks that install deps or start dev servers on worktree creation
- โขPerforming a full commit-merge-cleanup cycle locally without leaving the terminal
- โขQuick PR review by jumping directly to a PR's branch with `wt switch pr:123`
Installing Worktrunk
Install Worktrunk via Homebrew on macOS or Linux: `brew install worktrunk && wt config shell install`. On Windows, use Winget: `winget install max-sixty.worktrunk`, which installs as `git-wt` to avoid a conflict with Windows Terminal's `wt` alias. From source, run `cargo install worktrunk`. Arch Linux users can `sudo pacman -S worktrunk`. Conda and Pixi users find it in the conda-forge feedstock. After any install, run `wt config shell install` to enable shell integration that changes directories automatically.
Getting started with wt switch and wt list
Create a new worktree for a feature branch and switch to it with a single command: `wt switch --create feature-auth`. This creates the branch, the worktree directory, and drops you into it. Run `wt list` to see every worktree with its status, staged changes, and commit context. When done, `wt remove` cleans up the worktree and the branch. To launch Claude Code directly in a new worktree: `wt switch -x claude -c feature-b -- 'Fix pagination'`. The `-x` flag runs the following command after switching; everything after `--` passes through as arguments.
What Worktrunk adds over plain git
- โOne command replaces the three-to-four git operations normally needed to create a worktree and enter it
- โBranch names are the primary identifier, so path management becomes unnecessary for common operations
- โShell integration changes the working directory automatically when switching worktrees
- โInteractive picker shows CI status and PR summaries without leaving the terminal
- โShared build caches prevent rebuilding dependencies across ten worktrees on supported filesystems
- โNative launch support for Claude Code and Codex makes AI agent workflows feel designed, not bolted on
Constraints and edge cases
- โณShell integration (`wt config shell install`) is effectively required for the full experience, adding a setup step on every machine
- โณCopy-on-write build cache sharing works only on APFS, btrfs, and XFS; ext4 users lose this feature entirely
- โณWindows requires either disabling the Windows Terminal `wt` alias or using `git-wt` as the command name
- โณThe repository metadata shows the license field as unknown, which may matter for some compliance reviews
Other git worktree tools
Frequently asked questions
On macOS and Linux, Homebrew is the quickest route: brew install worktrunk && wt config shell install. Windows users run winget install max-sixty.worktrunk, which installs as git-wt to avoid clashing with Windows Terminal's wt alias. From source, use cargo install worktrunk. Arch Linux has it in pacman, and conda-forge distributes it for Conda and Pixi users.
Yes. Worktrunk was designed around these agents. Pass -x claude to wt switch to launch Claude Code after creating or entering a worktree, with arguments after -- forwarded to the agent. Codex is supported the same way. Each agent gets its own isolated working directory, so they won't overwrite each other's changes.
This command modifies your shell configuration so that Worktrunk can change the current working directory when you switch worktrees. Without it, wt switch enters the worktree but your terminal stays in the old directory. The integration works with bash, zsh, fish, nushell, and pwsh. You run it once per machine.
Yes. On supported filesystems, Worktrunk can make multiple worktrees share target/, node_modules/, and other build directories without copying or rebuilding them. This uses the filesystem's copy-on-write mechanism, so changes in one worktree stay isolated. The README calls this out as a specific workflow benefit for teams running many worktrees.
APFS (macOS default), btrfs (common on Linux), and XFS support the copy-on-write feature Worktrunk uses. ext4, the default on most Linux distributions, does not. If your build cache sharing doesn't appear to work, check your filesystem.
Hooks are custom commands that run at specific points: create, pre-merge, post-merge, and others. You can use them to install dependencies when a worktree is created, start a dev server, or run tests after a merge. Hooks are configured in Worktrunk's config file and can use per-branch variables for templating.
Who should try it โ and who should skip
Worktrunk is essential if you're running AI coding agents in parallel. If you're not yet using agents but manage multiple feature branches actively, the quality-of-life improvements still justify the install. Developers who work on a single branch or rarely juggle context should skip it; the overhead only pays off when the worktree count is two or more.
Related repositories
Is worktrunk worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of worktrunk.