Playbooks · Coding tasks
Manage Git worktrees for parallel AI agents with Worktrunk
Written November 6, 2026
Manages Git worktrees for parallel AI agents. What it does, what it needs, and where it breaks.
Agents like Claude Code and Codex can now handle long tasks without supervision, so running five to ten in parallel is realistic. Git's worktree feature gives each agent its own working directory, so they don't step on each other's changes — but the worktree commands are clumsy. Starting one means typing the branch name three times: git worktree add -b feat ../repo.feat, then changing directory by hand. Worktrunk is a command-line tool that reduces that to one command per worktree, with the parallel-agent workflow as its stated purpose.
The three core commands
Worktrunk addresses worktrees by branch name and computes paths from a configurable template. The core commands, from the project README:
| Task | Worktrunk | Plain git |
|---|---|---|
| Switch worktrees | wt switch feat | cd ../repo.feat |
| Create + start Claude | wt switch -c -x claude feat | git worktree add -b feat ../repo.feat && cd ../repo.feat && claude |
| Clean up | wt remove | cd ../repo && git worktree remove ../repo.feat && git branch -d feat |
| List with status | wt list | git worktree list (paths only) |
The -x flag runs a command after switching, and anything after -- is passed to it. That is the parallel-agent pattern in one line 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'
Each agent gets its own branch, its own directory, and its own task. Hooks automate the setup inside each worktree — installing dependencies, starting dev servers — so a new worktree is ready for the agent rather than empty.
What else it does
- Merge workflow:
wt mergesquashes, rebases onto main, merges, and cleans up in one command, generating the commit message from the diff. - Shared build caches: ten worktrees can share
target/,node_modules/, and similar directories without building or copying them — on APFS, btrfs, and XFS, the filesystems with copy-on-write support. - Status at a glance:
wt list --fullshows CI status and AI-generated summaries per branch; the interactive picker browses worktrees with streaming CI status and diff, log, PR, and comment previews. - PR checkout:
wt switch pr:123jumps straight to a pull request's branch. - Dev server per worktree: a
hash_porttemplate filter gives each worktree a unique port, so parallel dev servers don't collide. - Aliases and per-branch variables: custom
wt <name>commands and branch-scoped state for hook templates.
Install
Homebrew on macOS and Linux: brew install worktrunk && wt config shell install. Cargo: cargo install worktrunk && wt config shell install. On Windows, wt collides with Windows Terminal's command, so Winget installs it as git-wt. Arch Linux, Conda, and Pixi packages exist as well. The shell integration step matters: it is what lets wt switch change your directory.
Sandbox check: two worktrees, no agents
The worktree mechanics were checked in a scratch repository with Worktrunk v0.81.0, the release binary downloaded from the project's GitHub releases and matched against the release's published checksum. wt switch -c feature-a and wt switch -c feature-b each created a branch and a worktree next to the main checkout, and wt list showed all three with their status. Two things came out of the check. First, without shell integration installed, wt switch creates the worktree but prints "Cannot change directory — shell integration not installed" and stays put; run wt config shell install for the automatic directory change. Second, no agent was launched inside either worktree — the check covers worktree creation and listing, not an agent session, so the parallel-agent half of the workflow is the README's claim, not a measured result here.
Where it breaks
- Shell integration is not optional in practice. Without it, every switch leaves you in the old directory. Install it first, or the tool feels broken.
- Shared build caches need a copy-on-write filesystem. The cache sharing works on APFS, btrfs, and XFS. On other filesystems that feature does not apply, and each worktree builds on its own.
- Worktrees isolate directories, not merges. Two agents can still write conflicting changes to the same files on different branches; the conflict arrives at merge time, and Worktrunk does not resolve it for you.
- Windows users get a different command name. The binary is
git-wt, notwt, unless Windows Terminal's alias is disabled — every command in the documentation needs translating.
Related playbooks
- Zalando's broker hands agents OAuth safely
- Antigravity's remote agents run in Google's cloud
- Audit a repository's git config before any agent opens it
- Baseten Sandboxes keep agents running for days
Sources
- max-sixty/worktrunk — GitHub repository README: core commands, parallel-agent pattern, install methods
- Worktrunk documentation — full documentation, linked from the README: hooks, merge workflow, build caches
- Run parallel subagents in Claude Code — Agent Upstart: parallel subagents, the workflow Worktrunk gives directories to
- Have one agent write the code and a second agent check it in the background — Agent Upstart: running a builder and a reviewer at the same time
Back to: Coding playbooks hub · Also: Run parallel subagents in Claude Code · Have one agent write the code and a second agent check it in the background · Review Copilot's work in a nested Claude session