An open source project by Maximilian Roos (
max-sixty/worktrunk, MIT OR Apache-2.0).
Why it matters
AI agents like Claude Code and Codex can handle longer tasks without supervision, such that it’s possible to manage 5-10+ in parallel. Git’s native worktree feature gives each agent its own working directory, so they don’t step on each other’s changes.
But the git worktree UX is clunky. Even a task as small as starting a new worktree requires typing the branch name three times: git worktree add -b feat ../repo.feat, then cd ../repo.feat. Worktrunk addresses worktrees by branch name and computes paths from a configurable template, so its core commands make worktrees as easy as branches.
Core commands
| 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) |
Workflow automation
-
Hooks
Run commands on create, pre-merge, post-merge, and more. For example, install dependencies in
pre-start, start a dev server in the background withpost-start, and run tests inpre-merge. Project hooks (.config/wt.toml) require approval; user hooks do not. -
LLM commit messages
Worktrunk generates commit messages by building a templated prompt and piping it to an external command. This integrates with
wt merge,wt step commit, andwt step squash, and the docs include a Claude Code setup that runsclaude -pwith Haiku. -
Merge workflow
wt merge mainsquashes, rebases onto main, fast-forward merges, and cleans up in one command. For a PR workflow, commit withwt step commit, open the PR, and runwt removeafter it is merged. -
Share build caches
Ten worktrees get
target/,node_modules/, etc without building or copying them. Files are reflinked where the filesystem supports it (APFS, btrfs, XFS, ReFS); the docs cite a Rust first build dropping from ~68s to ~3s. -
wt list --fulland the interactive pickerCI status and AI-generated summaries per branch, plus a picker that browses worktrees with streaming CI status and diff, log, PR and comment previews.
-
More
wt switch pr:123jumps straight to a PR’s branch, thehash_porttemplate filter gives each worktree a unique dev server port, and aliases and per-branch variables add customwt <name>commands and branch-scoped state.
Claude Code plugin
Install with wt config plugins claude install. The plugin provides:
- Configuration skill (
/worktrunk) — helps set up LLM-generated commit messages, project hooks, and worktree path templates, and fix shell integration issues. Claude Code is designed to load the skill automatically when it detects worktrunk-related questions. - Activity tracking — status markers in
wt list: 🤖 means the agent is working, 💬 means it is waiting or idle. - Worktree isolation — when Claude Code agents run in isolated worktrees (
isolation: "worktree"), the plugin’sWorktreeCreateandWorktreeRemovehooks route this throughwt switch --createandwt remove, so agent-created worktrees get Worktrunk’s naming conventions, hooks, and lifecycle management. /wt-switch-createskill — starts a task in a fresh worktree without leaving the session./wt-diffpane — opens a pane beside the conversation that lists the worktrees the session has worked in, with the selected one’s diff below.
Separately, setting wt list statusline --format=claude-code as the statusLine command in ~/.claude/settings.json shows worktree status, model, context usage, and rate-limit pace in the Claude Code statusline.
How to use
# Install (macOS & Linux)
brew install worktrunk && wt config shell install
# Create a worktree for a new feature
wt switch --create feature-auth
# Check all worktrees
wt list
# When done, merge to main and clean up
wt merge main
For parallel agents, create multiple worktrees and launch an agent in each. The -x flag runs a command after switching; arguments after -- are passed to it.
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'
Notes
- Shell integration — run
wt config shell installafter installing so commands can change directories. - Windows naming conflict —
wtdefaults to Windows Terminal’s command. Use thegit-wtname Winget installs, or disable Windows Terminal’s app execution alias. - Filesystems without reflink — on ext4 and NTFS, build caches are copied in full.
/wt-diffpane requirement — the pane needs a Claude Code release that loads plugin hooks modules; earlier releases load the rest of the plugin without it.- LLM commit setup requirement — the documented
claude -p ... --safe-modecommand requires Claude Code ≥ 2.1.169. - Docs — full documentation is at worktrunk.dev, and the Claude Code integration is covered in Agent Integration.