Worktrunk is an open-source command-line tool that simplifies Git worktree management, especially for developers running multiple AI coding resources at the same time. Built by Max Sixty, it is a convenient interface for creating, modifying, registering, joining, and deleting active worktrees without having to use lengthy Git commands.
Git work trees allow multiple branches from the same repository to have separate working directories. This is especially useful when agents like Claude Code and OpenAI Codex are run in parallel, as each agent can work independently without affecting the other agent’s files.
Worktrunk builds on this functionality with additional automation, collaborative navigation, and development workflow features.
Features
Simplified Git Worktree Management
Worktrunk provides three core commands for everyday worktree operations:
wt switch switches between existing worktrees or creates new ones.
wt list displays worktrees with branch status and change information.
wt remove removes worktrees and their associated branches.
For example, creating a new feature branch and worktree requires only:
wt switch --create feature-auth
Worktrunk automatically creates the branch, prepares its working directory, and switches the shell into it.
This eliminates much of the repetitive work involved in managing Git worktrees manually.
Parallel AI Coding Agents
Worktrunk is particularly useful for developers working with multiple AI coding agents.
It can create a worktree and immediately launch an agent using the -x option:
wt switch -x claude --create feature-a -- "Implement user authentication"
Developers can repeat this process for different tasks, giving each agent its own branch and working directory.
This approach works with different command-line coding agents, including Claude Code and Codex. Worktrunk does not provide its own AI model or require users to replace their existing coding tools.
Automated Development Hooks
Worktrunk includes configurable hooks that execute commands during different stages of the worktree lifecycle.
Examples include:
Pre-start hooks for installing dependencies.
Post-start hooks for preparing development environments.
Pre-merge hooks for running tests and validation.
Post-merge hooks for cleaning up temporary resources.
Hooks can automate repetitive setup tasks whenever a new worktree is created.
For projects using Node.js, developers can configure dependency installation automatically. Other workflows can prepare databases, environment files, development servers, or additional resources.
Interactive Worktree Picker
Worktrunk provides an interactive interface for navigating existing worktrees.
Instead of remembering branch names and directory paths, developers can browse available worktrees and inspect their status.
The picker can display additional information, including Git diffs, commit history, pull requests, comments, and CI status.
This becomes increasingly useful when managing many parallel development tasks.
Shared Build Caches
One challenge with Git worktrees is that each working directory can require its own dependency installation and build output.
Worktrunk addresses this through copy-on-write build cache sharing.
It supports sharing directories such as node_modules/ and Rust's target/ across worktrees on supported filesystems, including APFS, Btrfs, and XFS.
This can significantly reduce redundant disk usage and avoid repeatedly rebuilding dependencies.
The feature depends on filesystem support and appropriate configuration. It should not be assumed to work identically on every operating system or storage configuration.
Git Merge and Cleanup
Worktrunk provides a simplified merge workflow that can handle committing, rebasing, merging, and cleaning up a completed worktree.
For example:
wt merge main
The command can prepare changes, generate a commit message when configured, merge the branch into the target, and remove the completed worktree.
This reduces the number of manual Git operations required to finish a development task.
Pull Request Integration
Worktrunk supports switching directly to pull request branches.
For example:
wt switch pr:123
It can also display CI status and pull request information through its listing and interactive navigation features.
This makes it easier to move between local development branches and remotely hosted contributions.
Custom Commands and Configuration
Worktrunk supports aliases, custom commands, configurable worktree paths, and per-branch variables.
Developers can use these features to build project-specific workflows without maintaining separate shell scripts for every operation.
Its configuration system also supports LLM-generated commit messages, allowing developers to generate commit descriptions from their changes when an appropriate AI tool is configured.
Download Worktrunk v0.81.0 - Software Mirrors |
|---|
Worktrunk v0.81.0 for Windowsworktrunk-x86_64-pc-windows-msvc.zip | 16.65 MB |
Worktrunk v0.81.0 for macOSworktrunk-x86_64-apple-darwin.tar.xz | 6.87 MB worktrunk-aarch64-apple-darwin.tar.xz | 6.27 MB |
Worktrunk v0.81.0 for Linuxworktrunk-x86_64-unknown-linux-musl.tar.xz | 7.99 MB worktrunk-aarch64-unknown-linux-musl.tar.xz | 7.01 MB |
Others Download related to Worktrunk v0.81.0wt.rb | 2.58 kB worktrunk-installer.sh | 52.25 kB worktrunk-installer.ps1 | 20.86 kB source.tar.gz | 3.91 MB sha256.sum | 610 B |
Worktrunk v0.81.0 Source CodeWorktrunk v0.81.0 Source code (zip) Worktrunk v0.81.0 Source code (tar.gz) |
Worktrunk v0.81.0 Release Notes:Release NotesImprovedHooks can prompt: hooks that run serially in the foreground (pre-* hooks, wt hook --foreground) inherit wt's stdin, so gum confirm 'trust this worktree?' && mise trust works as a hook. Concurrent and background hooks read EOF. (Breaking: hooks no longer receive their context as JSON on stdin; pass values as template arguments, or whole objects with the new tojson filter. wt step for-each keeps its JSON.) Docs (#3129, #4451, #4524, thanks @endigma for #3093)
Experimental wt switch --path: places one worktree outside the worktree-path template and keeps its branch name, as in wt switch --create feature/JIRA-1234 --path ../dark-mode. Commands reach it by branch or by path. Docs (#4317, thanks @christowiz for #1982)
wt merge --branch: merges another worktree's branch without leaving the current worktree. Commit, squash, rebase, and hooks run in the source worktree, and cleanup removes it. Docs (#4360, thanks @liuyinchu)
OpenCode 2 worktrees go through Worktrunk: after re-running wt config plugins opencode install, worktrees OpenCode creates and removes use wt switch --create and wt remove, as the Claude Code plugin's do. OpenCode's worktree.directory stops applying, and new branches start from the default branch. Like the Claude Code plugin, it opens an existing branch's worktree, which OpenCode's remove then removes. Docs (#4489, thanks @rzane for #4488)
Faster bulk removal: removal hands files to one background deleter per repository, not one rm -rf each, and deletes read-only directories it used to leave in .git/wt/trash. wt step prune no longer stalls when two worktrees share a directory name, as Codex worktrees do. (Breaking: prune runs pre-remove hooks concurrently; hooks writing shared state must coordinate.) (#4516, #4361, #4337)
wt switch - returns to the worktree it left, including a detached worktree or the second checkout of a branch, and wt remove - targets the same worktree. Pre-switch hooks see the resolved destination, so wt switch origin/feature passes branch=feature. (Breaking: from a bare repository's directory, commands given no argument act on the worktree of the branch HEAD names.) (#4497, #4496, #4521)
Template errors name the variable: {{ brnch }} reports undefined variable brnch and suggests branch. (Breaking: filters such as sanitize reject an undefined input, so {{ upstream | sanitize }} needs a guard or default on a branch with no upstream.) (#4350, #4440)
Templates use MiniJinja 3 (Breaking): objects and lists render Python-style ({'port': 3000}) instead of as JSON, so use | tojson where JSON is needed; round rounds half to even; title capitalizes fewer word boundaries (feat/x-y becomes Feat/x-Y); division by zero errors. (#4442, #4524)
CI status shows ⚠ for any failed forge call, where some failures, such as a Gitea 404, used to leave the cell blank. A forge CLI with no login for the host still leaves it blank, and wt config show --full names the host it checked. (#4436, #4449)
Removal explains itself: --force lists the changes it discards, and a refusal over untracked files suggests git stash -u. A multi-target wt remove continues past a target whose pre-remove hook or removal fails, and exits 1. A branch-only removal names the detached worktree left at the branch's path. (#4347, #4357, #3791, #4313, thanks @chachi for #3769)
Shell integration: wt merge and wt remove suggest restarting the shell when integration is installed but inactive. On Unix, the PowerShell profile comes from the installed pwsh, so a custom XDG_CONFIG_HOME works. (Breaking: installing for Nushell requires nu, and for PowerShell on Unix, pwsh.) (#4343, #4422, #4436)
System config has one path per platform: /Library/Application Support/worktrunk/config.toml on macOS, %PROGRAMDATA%\worktrunk\config.toml on Windows, /etc/xdg/worktrunk/config.toml elsewhere, or WORKTRUNK_SYSTEM_CONFIG_PATH. (Breaking: $XDG_CONFIG_DIRS is ignored and macOS no longer falls back to /etc/xdg; a file there stops loading without a warning.) (#4169)
expected_worktree_path_of_branch() template function: returns where wt switch --create would put a branch's worktree, even after the worktree at that path has moved to another branch. (#4502, thanks @BenJurewicz for #4480)
Smaller improvements: wt switch --create reports an invalid branch name in one line instead of Git's error; hook failures name the hook's source (pre-merge user:lint failed (exit code 7)); the wt list loading footer says how many rows fit; wt step for-each labels detached worktrees by path; install-statusline keeps settings.json's key order; the Codex plugin shows the Worktrunk icon. (#4349, #4352, #4333, #4498, #4420, #4327)
FixedForeground hooks that change terminal settings: a hook that touched the terminal, such as turbo on a cache miss, was stopped by SIGTTOU and wt hung. Hooks now run in the shell's job group. (Breaking: Nushell integration requires Nushell 0.113+; on Ctrl-C wt dies by the signal instead of exiting 130, so a calling script stops too.) (#4400, #3129, thanks @user753 for #4389 and @willparsons for the turbo report)
Formatter pre-commit hooks during a squash: in wt merge and wt step squash, a hook's edits missed the squash commit, and the dirty worktree blocked removal. All commit paths now stage, run the hooks, and stage again. (Breaking: wt step commit and wt merge --no-squash stage first too, so index-reading hooks like pre-commit run can block them.) (#4321, #4520)
wt step copy-ignored on Linux: copied files took the copy's time, so cargo rebuilt much of a copied target/; they now keep the source's mtime, as they already did on macOS and Windows. A reflink rejected with EPERM now falls back to a copy. (#4319, #4518, #4434, thanks @dmy-gh for #4248, @paul-hansen for the repro, and @HN05 for #4433)
wt list status symbols: JSON symbols strings use the table's order (⊘_, was _⊘), and the flag for an off-template path or duplicate checkout is a dim ⚐ instead of ⚑. (Breaking: consumers matching these strings need updating.) (#4335, #4334)
wt switch: --create branches from a remote-tracking default branch such as git-p4's p4/master instead of HEAD; switching by path, as the picker does, gives pre-switch hooks the destination's variables; the bare-repo warning names the configured path. (#4482, #4493, #4491, thanks @cazador481 for #4481 and @dlecan for #4492)
Agent plugins: claude --worktree NAME opens the worktree of an existing branch NAME rather than failing, so a kept session can be reopened. A clean exit then runs wt remove on it, which deletes its ignored files and, if integrated, the branch. The Codex plugin's Windows hooks parse under PowerShell. (#4487, #4241, thanks @edziegle for #4486 and @wstczyw for #4239)
wt switch picker: a per-project pager applies to the diff preview; a selected branch-only row no longer draws light text on the light selection bar; an orphan branch's log tab shows its commits. (#4398, #4408, #4470, thanks @willparsons for reporting the contrast bug)
wt step relocate: a swap moves the shell with its worktree; relocating the main worktree leaves a shell in a nested worktree where it is; branches whose sanitized names collide no longer relocate partway. (#4325, #4256, thanks @Duang777)
Config errors: a malformed approvals.toml no longer aborts hooks, aliases, or commits run with --yes; one invalid WORKTRUNK_* override no longer discards the valid ones. (#4467, #4348)
Windows: an Azure CLI installed through WinGet (az.cmd) is found, and Git Bash is found through the first git on PATH, including custom installs where it resolves under Git\mingw64\bin. (Breaking: without git on PATH, Git Bash is no longer found at its default install locations.) (#4402, #4411, #4452, thanks @wmmc88 for #4401 and @LeoWSY-hashblue for #4410)
Forge fixes: Azure DevOps CI no longer shows a same-named branch's PR from another repository in the project, and pr:N suggests a dev.azure.com URL for SSH remotes; Gitea fork pushes keep the server's clone URL; tea logins in its default macOS and Windows locations are found; gh and glab protocol settings apply per host. (#4326, #4364, #4495, #4420)
Fixes for unusual setups: valueless git config keys such as core.fsmonitor read as true; untracked files named like :x no longer break wt list's diff; worktree paths containing newlines or non-UTF-8 bytes; the statusline's branch label with custom worktree-path templates; zsh compinit advice names the right file; IPv6 ssh:// remotes get distinct approvals and projects] settings (Breaking: re-save them). ([#4314, #4320, #4453, #4495, #4421, #4526)
Documentationwt config shell --help is the shell setup reference, covering init, install, uninstall, and diagnostics. (#4344)
Doc corrections: the wt config state vars clear example, wt list JSON null causes, every supported forge in CI help, --path worktrees in wt list, the bare-repo navigation example, and Alt as Option on macOS. (#4363, #4359, #4439, #4328, #4483, #4412, thanks @wmcnamee-coreweave for #4474)
Recipes: the bare repository layout sets origin's fetch refspec; the aichat example passes --code to drop a reasoning model's <think> block; the OpenCode command uses Claude Haiku 5.5; wt-tui joins the custom subcommand examples. (#4323, #4332, #4432, #4386, thanks @gitNetw0rk for #4322, @FenjuFu, and @marcusjihansson)
InternalLibrary API changes (Breaking library API): Repository::project_identifier returns a ProjectId, which config accessors take in place of &str; Repository::require_worktree also returns the branch; Repository::run_command takes AsRef arguments; UserConfig::expected_worktree_path is new. (#4526, #4496, #4453, #4502)
Install worktrunk 0.81.0Install prebuilt binaries via shell scriptcurl --proto '=https' --tlsv1.2 -LsSf https://github.com/max-sixty/worktrunk/releases/download/v0.81.0/worktrunk-installer.sh | sh && wt config shell install
Install prebuilt binaries via powershell scriptpowershell -ExecutionPolicy Bypass -c "irm https://github.com/max-sixty/worktrunk/releases/download/v0.81.0/worktrunk-installer.ps1 | iex"; git-wt config shell install
Install prebuilt binaries via Homebrewbrew install worktrunk && wt config shell install
Download worktrunk 0.81.0Install via Cargocargo install worktrunk && wt config shell install
Install via Winget (Windows)winget install max-sixty.worktrunk && git-wt config shell install
Install via AUR (Arch Linux)paru worktrunk-bin && wt config shell install
|
Performance and Compatibility
Worktrunk is written in Rust and distributed as a native command-line application. It does not require a background server or introduce an additional AI runtime.
Its main workload involves Git operations, filesystem management, shell integration, and optional workflow automation. Consequently, its performance depends more on repository size, filesystem behavior, and configured hooks than on AI model processing.
It supports macOS, Linux, and Windows. Installation is available through Homebrew, Cargo, Winget, and several Linux package managers.
Shell integration is available for supported shells, allowing commands such as wt switch to change the current directory directly.
Windows users should note that wt can conflict with the Windows Terminal command alias. The Winget installation provides git-wt as an alternative.
System Requirements
Worktrunk requires:
Git installed and accessible through the system PATH.
A supported operating system: Windows, macOS, or Linux.
A compatible shell for directory-switching integration.
A Git repository for worktree operations.
Optional requirements depend on the features being used:
Cargo and Rust for building from source.
jq for certain integrations and scripts.
A compatible AI coding agent for automated agent workflows.
A supported filesystem for copy-on-write cache sharing.
Pros and Cons
Pros
Simplifies Git worktree creation and management.
Designed for parallel AI coding workflows.
Supports Claude Code and other command-line agents.
Automates development tasks through hooks.
Provides interactive worktree navigation.
Supports shared build caches.
Includes merge, cleanup, and pull request workflows.
Written in Rust and open-source.
Supports Windows, macOS, and Linux.
Cons
Requires familiarity with Git worktrees to use its advanced features effectively.
Shell integration requires additional configuration.
Copy-on-write cache sharing depends on filesystem compatibility.
Some advanced features require external tools.
Does not provide AI models or coding agents itself.
How to Install
The easiest installation method on macOS and Linux is Homebrew:
brew install worktrunk
wt config shell install
For installation through Cargo:
cargo install worktrunk
wt config shell install
On Windows, use Winget:
winget install max-sixty.worktrunk
git-wt config shell install
Arch Linux users can install it through Pacman:
sudo pacman -S worktrunk
wt config shell install
After installation, restart the terminal or reload the shell configuration.
Verify the installation with:
wt --help
wt list
To create a new worktree:
wt switch --create feature-test
The official documentation provides additional configuration examples for hooks, aliases, build caches, and parallel AI agent workflows.
Final Verdict
Worktrunk is an excellent utility for developers who frequently work with multiple Git branches, especially those using AI coding agents.
Its biggest advantage is that it makes Git worktrees considerably easier to manage. Features such as automated hooks, shared build caches, interactive navigation, and integrated merge workflows turn what would otherwise be repetitive Git operations into a more organized development process.
It is not an AI coding assistant itself, but it complements tools such as Claude Code and Codex by providing isolated environments for parallel development.
For developers who regularly run multiple coding agents or maintain several features simultaneously, Worktrunk is a practical addition to their development toolkit.
Sources
