Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

Simplify README and docs wording for clarity

Maximilian Roose11df33077bc
diff --git a/README.md b/README.md
index 14c902ea6..2d632cf6e 100644
--- a/README.md
+++ b/README.md
@@ -23,13 +23,13 @@ Worktrunk is a CLI for git worktree management, designed for parallel AI agent w
AI agents like Claude and Codex can increasingly handle longer tasks without supervision. Running several in parallel is practical. But on a single checkout they step on each other's uncommitted changes.
-Git worktrees solve this: multiple working directories backed by one `.git`. Each gets its own files and index while sharing the repository's history and objects.
+Git worktrees solve this: multiple working directories sharing one `.git`.
-But the built-in commands are path-oriented: `git worktree add ../repo.feature`, then `cd ../repo.feature`, then later `git worktree remove ../repo.feature`.
+But the built-in commands are path-oriented: `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. Both for basic branch-based navigation & status....
+Worktrunk makes worktrees easy to use — branch-based navigation, unified status, and workflow automation:
| Task | Worktrunk | Plain git |
|------|-----------|-----------|
@@ -38,8 +38,6 @@ Worktrunk makes worktrees easy to use. Both for basic branch-based navigation &
| 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) |
-...and automating a bunch of workflows, including:
-
- **[Lifecycle hooks](https://worktrunk.dev/hooks/)** — run commands on create, switch, merge (deps install, dev servers, test suites)
- **[LLM commit messages](https://worktrunk.dev/llm-commits/)** — generate commits from diffs via [llm](https://llm.datasette.io/)
- **[Merge workflow](https://worktrunk.dev/merge/)** — squash, rebase, push, clean up in one command
@@ -93,8 +91,6 @@ $ wt remove
<!-- END AUTO-GENERATED -->
-Worktrunk checks if changes are already on main before deleting the branch.
-
## Install
**Homebrew (macOS & Linux):**
diff --git a/docs/content/why-worktrunk.md b/docs/content/why-worktrunk.md
index 5f916a7f2..08c2319d4 100644
--- a/docs/content/why-worktrunk.md
+++ b/docs/content/why-worktrunk.md
@@ -7,17 +7,17 @@ Worktrunk is a CLI for git worktree management, designed for parallel AI agent w
![Worktrunk Demo](/assets/wt-demo.gif)
-## Git worktrees
+## Context: git worktrees
-AI agents like Claude and Codex can increasingly handle longer tasks without supervision. Running several in parallel is practical. But on a single checkout they step on each other's uncommitted changes.
+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 solve this: multiple working directories backed by one `.git`. Each gets its own files and index while sharing the repository's history and objects.
+Git worktrees are a great primitive for this: multiple working directories sharing one `.git`.
-But the built-in commands are path-oriented: `git worktree add ../repo.feature`, then `cd ../repo.feature`, then later `git worktree remove ../repo.feature`.
+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. Both for basic branch-based navigation & status....
+Worktrunk makes worktrees easy to use — branch-based navigation, unified status, and workflow automation:
| Task | Worktrunk | Plain git |
| --------------------- | -------------------------------- | ----------------------------------------------------------------------------- |
@@ -26,8 +26,6 @@ Worktrunk makes worktrees easy to use. Both for basic branch-based navigation &
| 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) |
-...and automating a bunch of workflows, including:
-
- **[Lifecycle hooks](@/hooks.md)** — run commands on create, pre-merge, post-merge
- **[LLM commit messages](@/llm-commits.md)** — generate commit messages from diffs via [llm](https://llm.datasette.io/)
- **[Merge workflow](@/merge.md)** — squash, rebase, merge, clean up in one command
@@ -62,10 +60,11 @@ See all worktrees at a glance:
{% terminal() %}
<span class="prompt">$</span> <span class="cmd">wt list</span>
- <b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Path</b> <b>Remote⇅</b> <b>Commit</b> <b>Age</b> <b>Message</b>
-@ <b>feature-api</b> <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <b>./repo.feature-api</b> <span class=g>⇡3</span> <span class=d>28d38c20</span> <span class=d>30m</span> <span class=d>Add API tests</span>
-^ main <span class=d>^</span><span class=d>⇅</span> ./repo <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=d>2e6b7a8f</span> <span class=d>4d</span> <span class=d>Merge fix-auth:…</span>
-+ fix-auth <span class=d>↕</span><span class=d>|</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> ./repo.fix-auth <span class=d>|</span> <span class=d>1d697d5b</span> <span class=d>5h</span> <span class=d>Add secure token…</span>
+<b>Branch</b> <b>Status</b> <b>HEAD±</b> <b>main↕</b> <b>Path</b> <b>Remote⇅</b> <b>Commit</b> <b>Age</b> <b>Message</b>
+@ <b>feature-api</b> <span class=c>+</span> <span class=d>↕</span><span class=d>⇡</span> <span class=g>+54</span> <span class=r>-5</span> <span class=g>↑4</span> <span class=d><span class=r>↓1</span></span> <b>./repo.feature-api</b> <span class=g>⇡3</span> <span class=d>28d38c20</span> <span class=d>30m</span> <span class=d>Add API tests</span>
+^ main <span class=d>^</span><span class=d>⇅</span> ./repo <span class=g>⇡1</span> <span class=d><span class=r>⇣1</span></span> <span class=d>2e6b7a8f</span> <span class=d>4d</span> <span class=d>Merge fix-auth:…</span>
+
+- fix-auth <span class=d>↕</span><span class=d>|</span> <span class=g>↑2</span> <span class=d><span class=r>↓1</span></span> ./repo.fix-auth <span class=d>|</span> <span class=d>1d697d5b</span> <span class=d>5h</span> <span class=d>Add secure token…</span>
⚪ <span class=d>Showing 3 worktrees, 1 with changes, 2 ahead</span>
{% end %}
@@ -85,8 +84,6 @@ Clean up when done:
<!-- END AUTO-GENERATED -->
-Worktrunk checks if changes are already on main before deleting the branch.
-
## Install
**Homebrew (macOS & Linux):**
@@ -112,8 +109,6 @@ $ wt config shell install
## Further reading
-Resources on git worktrees and AI agent workflows:
-
- [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