Worktrunk

Why Worktrunk?

Commands

wt switch

wt list

wt remove

wt merge

wt select

wt config

wt step

Reference

Hooks

LLM Commit Messages

Claude Code Integration

Tips & Patterns

FAQ

Why Worktrunk?

Worktrunk is a CLI for git worktree management, designed for parallel AI agent workflows. Git worktrees give each agent an isolated branch and directory; Worktrunk adds branch-based navigation, unified status, and lifecycle hooks. Creating a new agent workspace is as immediate as git switch.

Here's a quick demo:

Worktrunk demo showing wt list, wt switch, and wt merge — Listing worktrees, creating one, working, merging back

Context: git worktrees

AI agents like Claude and Codex can increasingly handle longer tasks without supervision, and it's very practical to run several in parallel. But on a single file tree they step on each other's uncommitted changes.

Git worktrees are a great primitive for this: multiple working directories sharing one .git.

But git worktrees' UX is clunky: git worktree add -b feature ../repo.feature, then cd ../repo.feature, then git worktree remove ../repo.feature.

What Worktrunk adds

Worktrunk makes worktrees easy to use — branch-based navigation, unified status, and workflow automation.

Core commands:

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

Workflow automation:

Lifecycle hooks — run commands on create, pre-merge, post-merge
LLM commit messages — generate commit messages from diffs via llm
Merge workflow — squash, rebase, merge, clean up in one command
...and lots more.

Core commands in practice

Create a worktree for a new task:

$ wt switch --create fix-auth
✅ Created new worktree for fix-auth from main at ../repo.fix-auth

Switch to an existing worktree:

$ wt switch feature-api
✅ Switched to worktree for feature-api at ../repo.feature-api

See all worktrees at a glance:

$ wt list
  Branch       Status         HEAD±    main↕  Path                Remote⇅  Commit    Age   Message
@ feature-api  +   ↕⇡      +54   -5   ↑4  ↓1  ./repo.feature-api   ⇡3      28d38c20  30m   Add API tests
^ main             ^⇅                         ./repo               ⇡1  ⇣1  2e6b7a8f  4d    Merge fix-auth:…
+ fix-auth         ↕|                 ↑2  ↓1  ./repo.fix-auth        |     1d697d5b  5h    Add secure token…

⚪ Showing 3 worktrees, 1 with changes, 2 ahead

Clean up when done:

$ wt remove
🔄 Removing feature-api worktree & branch in background (already in main)

Install

Homebrew (macOS & Linux):

$ brew install max-sixty/worktrunk/wt
$ wt config shell install  # allows commands to change directories

Cargo:

$ cargo install worktrunk
$ wt config shell install

Next steps

Learn the core commands: wt switch, wt list, wt merge, wt remove
Set up project hooks for automated setup
Explore LLM commit messages, fzf-like picker, Claude Code integration
Run wt --help or wt <command> --help for quick CLI reference