Skip to content

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

docs: Update README with clearer explanations and examples

Maximilian Roos636e94cce6e7
diff --git a/README.md b/README.md
index eeaf90314..5d2bd451f 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,8 @@ $ wt switch --create fix-auth
✅ Created new worktree for fix-auth from main at ../repo.fix-auth/
```
+...then do work. Then...
+
**After making changes, merge it back:**
<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_simple.snap -->
@@ -50,7 +52,7 @@ $ wt merge
See [`wt merge`](#wt-merge) for all options.
-**See all active worktrees:**
+**See all worktrees:**
<!-- Output from: tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap -->
@@ -77,19 +79,26 @@ See [Shell Integration](#shell-integration) for details.
## Design Philosophy
-Worktrunk is opinionated! It's not designed to be all things to all people. The choices optimize for agent workflows:
+Worktrunk is opinionated! It's not designed to be all things to all people. Its
+choices optimize for parallel AI agent workflow:
- Trunk-based development
- Lots of short-lived worktrees
-- Terminal-based coding agents
-- Inner dev loops are local
-- Shell navigation
- Commits are squashed into linear histories
-- Maximum automation
-- Branches as handles, one branch per worktree
+- Terminal-based coding agents, shell navigation
+- Inner dev loops are local
-Adopting Worktrunk for a portion of a workflow doesn't require adopting it for
-everything — standard `git worktree` commands continue working fine.
+...and that means...
+
+- Total focus on zero-ing the cost of additional agents worktree
+- Fairly small surface area: three core commands
+- Maximum automation: LLM commit messages, lifecycle hooks, Claude Code hooks
+ - A robust "run auto-merge when 'local-CI' passes" command
+- Worktrees are addressed by their branch
+- Extreme UI responsiveness; slow ops can't delay fast ones
+- Pluggable; adopting Worktrunk for a portion of a workflow doesn't require
+ adopting it for everything. standard `git worktree` commands continue working
+ fine!
## Automation Features
@@ -239,21 +248,19 @@ $ wt merge
### Shell Integration
-Worktrunk can automatically configure the shell:
+Worktrunk requires shell integration in order to switch directories, during `wt
+switch` & `wt merge`/`wt remove`. To add automatic setup to shell config files
+(supports Bash, Zsh, and Fish):
```bash
wt config shell
```
-This adds shell integration to config files (supports Bash, Zsh, and Fish). The
-integration enables `wt switch` to change directories and `wt remove` to return
-to the previous location.
-
For manual setup instructions, see `wt config shell --help`.
## Tips
-**Create an alias for an agent** - Shell aliases streamline common workflows. For example, to create a worktree and immediately start Claude:
+**Create an alias for an agent** — Shell aliases streamline common workflows. For example, to create a worktree and immediately start Claude:
```bash
alias wsl='wt switch --create --execute=claude'
@@ -261,35 +268,25 @@ alias wsl='wt switch --create --execute=claude'
Now `wsl new-feature` creates a branch, sets up the worktree, runs initialization hooks, and launches Claude in that directory.
-**Automatic branch status in Claude Code** - The Claude Code integration shows
+**Automatic branch status in Claude Code** — The Claude Code integration shows
which branches have active sessions. When Claude starts working, the branch
shows `🤖` in `wt list`. When waiting for input, it shows `💬`. Setup
instructions: [Custom Worktree Status](#custom-worktree-status).
-**Auto-generated commit messages** - Simon Willison's
-[llm](https://llm.datasette.io/) tool works with worktrunk's
-commit generation. Install it, configure the command, and `wt merge` will
-automatically generate contextual commit messages. Setup guide: [LLM Commit
-Messages](#llm-commit-messages).
+**Auto-generated commit messages** — Configure an LLM to generate commit
+messages during merge. See [LLM Commit Messages](#llm-commit-messages).
-**Environment setup with hooks** - Use `post-create-command` (or
-`post-start-command` for non-blocking) to run setup for that
-path. See [Project Hooks](#project-hooks) for details:
+**Automate startup with hooks** — Use `post-create-command` for environment
+setup, `post-start-command` for non-blocking tasks. For example, worktrunk uses
+`post-start-command` to bootstrap build caches from main via copy-on-write,
+eliminating cold compiles (see [worktrunk's config](.config/wt.toml)). See
+[Project Hooks](#project-hooks) for details.
-```toml
-# In .config/wt.toml
-[post-create-command]
-"setup" = "uv sync && nvm install"
-```
-
-**Use hooks to reduce iteration times** - [Project hooks](#project-hooks) can
-dramatically speed up your workflow. For example, use `post-start-command` to
-bootstrap new worktrees with pre-compiled dependencies from main via
-copy-on-write, eliminating cold compiles while keeping caches isolated (see
-[worktrunk's own config](.config/wt.toml)). Or use `post-merge-command` to
-automatically deploy to a staging server after every merge.
+**Use `post-merge-command` as a "local CI" running** — Running `wt merge` on a
+worktree, knowing it'll get merged iff passes tests — means `main` is protected from an agent
+forgetting to run all tests.
-**Delegate to task runners** - Reference existing Justfile/Makefile commands instead of duplicating logic:
+**Delegate to task runners** — Reference existing Justfile/Makefile commands instead of duplicating logic:
```toml
[post-create-command]
@@ -395,6 +392,7 @@ wt remove @ # Remove current worktree
</details>
<a id="wt-merge"></a>
+
<details>
<summary><strong><code>wt merge [target]</code></strong> - Merge, push, and cleanup</summary>
@@ -557,6 +555,7 @@ wt remove # (when already in main worktree)
</details>
<a id="wt-list"></a>
+
<details>
<summary><strong><code>wt list</code></strong> - Show all worktrees and branches</summary>