worktrunk 0.38.0

A CLI for Git worktree management, designed for parallel AI agent workflows
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214

+++
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.

Scaling agents becomes trivial. A quick demo:

<figure class="demo">
<picture>
  <source srcset="/assets/docs/dark/wt-core.gif" media="(prefers-color-scheme: dark)">
  <img src="/assets/docs/light/wt-core.gif" alt="Worktrunk demo showing wt list, wt switch, and hooks" width="1600" height="900">
</picture>
<figcaption>Listing worktrees, switching, cleaning up</figcaption>
</figure>

## 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.

> Start with the core commands

**Core commands:**

<table class="cmd-compare">
  <thead>
    <tr>
      <th>Task</th>
      <th>Worktrunk</th>
      <th>Plain git</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Switch worktrees</td>
      <td>{% rawcode() %}wt switch feat{% end %}</td>
      <td>{% rawcode() %}cd ../repo.feat{% end %}</td>
    </tr>
    <tr>
      <td>Create + start Claude</td>
      <td>{% rawcode() %}wt switch -c -x claude feat{% end %}</td>
      <td>{% rawcode() %}git worktree add -b feat ../repo.feat && \
cd ../repo.feat && \
claude{% end %}</td>
    </tr>
    <tr>
      <td>Clean up</td>
      <td>{% rawcode() %}wt remove{% end %}</td>
      <td>{% rawcode() %}cd ../repo && \
git worktree remove ../repo.feat && \
git branch -d feat{% end %}</td>
    </tr>
    <tr>
      <td>List with status</td>
      <td>{% rawcode() %}wt list{% end %}</td>
      <td>{% rawcode() %}git worktree list{% end %} (paths only)</td>
    </tr>
  </tbody>
</table>

> Expand into the more advanced commands as needed

**Workflow automation:**

- **[Hooks](@/hook.md)** — run commands on create, pre-merge, post-merge, etc
- **[LLM commit messages](@/llm-commits.md)** — generate commit messages from diffs
- **[Merge workflow](@/merge.md)** — squash, rebase, merge, clean up in one command
- **[Interactive picker](@/switch.md#interactive-picker)** — browse worktrees with live diff and log previews
- **[Copy build caches](@/step.md#wt-step-copy-ignored)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees
- **[`wt list --full`](@/list.md#full-mode)** — [CI status](@/list.md#ci-status) and [AI-generated summaries](@/list.md#llm-summaries) per branch
- **[PR checkout](@/switch.md#pull-requests-and-merge-requests)** — `wt switch pr:123` to jump straight to a PR's branch
- **[Dev server per worktree](@/hook.md#dev-servers)** — `hash_port` template filter gives each worktree a unique port
- **[Aliases](@/step.md#aliases) & [per-branch variables](@/config.md#wt-config-state-vars)** — custom `wt step <name>` commands and branch-scoped state for hook templates
- ...and **[lots more](#next-steps)**

A demo with some advanced features:

<figure class="demo">
<picture>
  <source srcset="/assets/docs/dark/wt-zellij-omnibus.gif" media="(prefers-color-scheme: dark)">
  <img src="/assets/docs/light/wt-zellij-omnibus.gif" alt="Worktrunk omnibus demo: multiple Claude agents in Zellij tabs with hooks, LLM commits, and merge workflow" width="1600" height="900">
</picture>
<figcaption>Multiple Claude agents in parallel with interactive picker, hooks, LLM commits, and merge</figcaption>
</figure>

## 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") }}

<details>
<summary><strong>Windows</strong></summary>

On Windows, `wt` defaults to Windows Terminal's command. 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 → Privacy & security → For developers → App Execution Aliases → disable "Windows Terminal") to use `wt` directly.

</details>

**Arch Linux:**

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

## Quick start

Create a worktree for a new feature:

<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__quickstart_switch.snap — edit source to update -->

{% terminal(cmd="wt switch --create feature-auth") %}
<span class="cmd">wt switch --create feature-auth</span>
<span class=g>✓</span> <span class=g>Created branch <b>feature-auth</b> from <b>main</b> and worktree @ <b>repo.feature-auth</b></span>
{% end %}

<!-- END AUTO-GENERATED -->

This creates a new branch and worktree, then switches to it. Do your work, then check all worktrees with [`wt list`](@/list.md):

<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__quickstart_list.snap — edit source to update -->

{% terminal(cmd="wt list") %}
<span class="cmd">wt list</span>
  <b>Branch</b>        <b>Status</b>        <b>HEAD±</b>    <b>main↕</b>  <b>Remote⇅</b>  <b>Commit</b>    <b>Age</b>   <b>Message</b>
@ feature-auth  <span class=c>+</span>   <span class=d>↑</span>      <span class=g>+27</span>   <span class=r>-8</span>   <span class=g>↑1</span>               <span class=d>4bc72dc9</span>  <span class=d>2h</span>    <span class=d>Add authentication module</span>
^ main              <span class=d>^</span><span class=d>⇡</span>                         <span class=g>⇡1</span>      <span class=d>0e631add</span>  <span class=d>1d</span>    <span class=d>Initial commit</span>

<span class=d>○</span> <span class=d>Showing 2 worktrees, 1 with changes, 1 ahead, 1 column hidden</span>
{% end %}

<!-- END AUTO-GENERATED -->

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:

<!-- ⚠️ AUTO-GENERATED-HTML from tests/snapshots/integration__integration_tests__list__quickstart_merge.snap — edit source to update -->

{% terminal(cmd="wt merge main") %}
<span class="cmd">wt merge main</span>
<span class=c>◎</span> <span class=c>Generating commit message and committing changes... <span style='color:var(--bright-black,#555)'>(2 files, <span class=g>+53</span></span></span>, no squashing needed<span style='color:var(--bright-black,#555)'>)</span>
<span style='background:var(--bright-white,#fff)'> </span> <b>Add authentication module</b>
<span class=g>✓</span> <span class=g>Committed changes @ <span class=d>a1b2c3d</span></span>
<span class=c>◎</span> <span class=c>Merging 1 commit to <b>main</b> @ <span class=d>a1b2c3d</span> (no rebase needed)</span>
<span style='background:var(--bright-white,#fff)'> </span> * <span style='color:var(--yellow,#a60)'>a1b2c3d</span> Add authentication module
<span style='background:var(--bright-white,#fff)'> </span>  auth.rs | 51 <span class=g>+++++++++++++++++++++++++++++++++++++++++++++++++++</span>
<span style='background:var(--bright-white,#fff)'> </span>  lib.rs  |  2 <span class=g>++</span>
<span style='background:var(--bright-white,#fff)'> </span>  2 files changed, 53 insertions(+)
<span class=g>✓</span> <span class=g>Merged to <b>main</b> <span style='color:var(--bright-black,#555)'>(1 commit, 2 files, +53</span></span><span style='color:var(--bright-black,#555)'>)</span>
<span class=c>◎</span> <span class=c>Removing <b>feature-auth</b> worktree &amp; branch in background (same commit as <b>main</b>,</span> <span class=d>_</span><span class=c>)</span>
<span class=d>○</span> Switched to worktree for <b>main</b> @ <b>repo</b>
{% end %}

<!-- END AUTO-GENERATED -->

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](@/hook.md#pre-start-vs-post-start) to automate setup (install deps, start dev servers).

## Next steps

- Learn the core commands: [`wt switch`](@/switch.md), [`wt list`](@/list.md), [`wt merge`](@/merge.md), [`wt remove`](@/remove.md)
- Set up [hooks](@/hook.md) for automated setup
- Explore [LLM commit messages](@/llm-commits.md), [interactive
  picker](@/switch.md#interactive-picker), [Claude Code integration](@/claude-code.md), [CI
  status & PR links](@/list.md#ci-status)
- Browse [tips & patterns](@/tips-patterns.md) for recipes: aliases, dev servers, databases, agent handoffs, and more
- [Extending Worktrunk](@/extending.md) — 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](https://www.anthropic.com/engineering/claude-code-best-practices) — Anthropic's official guide, including the worktree pattern
- [Shipping faster with Claude Code and Git Worktrees](https://incident.io/blog/shipping-faster-with-claude-code-and-git-worktrees) — incident.io's workflow for parallel agents
- [Git worktree pattern discussion](https://github.com/anthropics/claude-code/issues/1052) — Community discussion in the Claude Code repo
- [@DevOpsToolbox's video on Worktrunk](https://youtu.be/WBQiqr6LevQ?t=345)
- [git-worktree documentation](https://git-scm.com/docs/git-worktree) — Official git reference