max-sixty__worktrunk/docs/content/worktrunk.md

+++ title = "Worktrunk" description = "CLI for Git worktree management, designed for parallel AI agent workflows." weight = 1

[extra] canonical = "/" +++

Worktrunk is a CLI for git worktree management, designed for running AI agents in parallel.

Worktrunk's three core commands make worktrees as easy as branches. Plus, Worktrunk has a bunch of quality-of-life features to simplify working with many parallel changes, including hooks to automate local workflows.

A quick demo:

Listing worktrees, switching, cleaning up

Context: git worktrees

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 give 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 makes git worktrees as easy as branches

Worktrees are addressed by branch name; paths are computed from a configurable template. Commands that take a branch also accept the path of the worktree it is checked out in.

Start with the core commands

Core commands:

Task	Worktrunk	Plain git
Switch worktrees	{% rawcode() %}wt switch feat{% end %}	{% rawcode() %}cd ../repo.feat{% end %}
Create + start Claude	{% rawcode() %}wt switch -c -x claude feat{% end %}	{% rawcode() %}git worktree add -b feat ../repo.feat && \ cd ../repo.feat && \ claude{% end %}
Clean up	{% rawcode() %}wt remove{% end %}	{% rawcode() %}cd ../repo && \ git worktree remove ../repo.feat && \ git branch -d feat{% end %}
List with status	{% rawcode() %}wt list{% end %}	{% rawcode() %}git worktree list{% end %} (paths only)

Expand into the more advanced commands as needed

Workflow automation:

• 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
• Copy build caches — skip cold starts by sharing target/, node_modules/, etc between worktrees
• 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

Multiple parallel agents, same simple commands:

Multiple Claude agents in parallel with interactive picker, hooks, LLM commits, and merge

Install

Homebrew (macOS & Linux):

{{ terminal(cmd="brew install worktrunk && wt config shell install") }}

Shell integration allows commands to change directories.

Cargo:

{{ terminal(cmd="cargo install worktrunk && wt config shell install") }}

Windows & other

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

{{ terminal(cmd="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.

Free code signing provided by SignPath.io, certificate by SignPath Foundation — policy.

Arch Linux:

{{ terminal(cmd="sudo pacman -S worktrunk && wt config shell install") }}

Conda / Pixi (community-maintained feedstock):

{{ terminal(cmd="conda install -c conda-forge worktrunk && wt config shell install") }}

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

Quick start

Create a worktree for a new feature:

{% terminal(cmd="wt switch --create feature-auth") %} wt switch --create feature-auth ✓ Created branch feature-auth from main and worktree @ ~/repo.feature-auth {% end %}

This creates a new branch and worktree, then switches to it. Do your work, then check all worktrees with wt list:

{% terminal(cmd="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, 1 column hidden {% end %}

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

When done, either:

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

{{ terminal(cmd="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:

{% terminal(cmd="wt merge main") %} 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 {% end %}

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

{{ terminal(cmd="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 deps, start dev servers).

Next steps

• Learn the core commands: wt switch, wt list, wt merge, wt remove
• Set up hooks for automated setup
• Explore LLM commit messages, interactive picker, Claude Code integration, CI status & PR links
• Browse tips & patterns for recipes: aliases, dev servers, databases, agent handoffs, and more
• Extending Worktrunk — customize workflows with hooks & aliases
• Run wt --help or wt <command> --help for quick CLI reference

Further reading

• Claude Code: Best practices for agentic coding — Anthropic's official guide, including the worktree pattern
• Shipping faster with Claude Code and Git Worktrees — incident.io's workflow for parallel agents
• Git worktree pattern discussion — Community discussion in the Claude Code repo
• @DevOpsToolbox's video on Worktrunk
• git-worktree documentation — Official git reference