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.mdindex 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 mergeSee [`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):```bashwt 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:```bashalias 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 showswhich branches have active sessions. When Claude starts working, the branchshows `🤖` in `wt list`. When waiting for input, it shows `💬`. Setupinstructions: [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>