Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: Refine and enhance README for clarity and consistency
Maximilian Roos3f39d8397d7a
diff --git a/README.md b/README.mdindex e2fa4e5bc..d24a2b0d8 100644--- a/README.md+++ b/README.md@@ -1,3 +1,5 @@+<!-- markdownlint-disable MD014 MD024 MD033 -->+# Worktrunk<!-- User badges -->@@ -18,23 +20,23 @@ switch`.## December 2025 Project Status-I've been using Worktrunk as my daily driver while building it for the past-couple of months, and am releasing it as Open Source this week. It's built with love-(no slop!). If some social proof is helpful: I also created-[PRQL](https://github.com/PRQL/prql) (10k stars) and am a maintainer of-[Xarray](https://github.com/pydata/xarray) (4k stars),+I've been using Worktrunk as my daily driver, and am releasing it as Open Source+this week. It's built with love (no slop!). If some social proof is helpful: I+also created [PRQL](https://github.com/PRQL/prql) (10k stars) and am a+maintainer of [Xarray](https://github.com/pydata/xarray) (4k stars),[Insta](https://github.com/mitsuhiko/insta), &[Numbagg](https://github.com/numbagg/numbagg).Currently, Worktrunk:-- simplifies standard worktree workflows — an easier way to create / navigate /- list / clean up git worktrees.+- simplifies standard worktree workflows — an easier, simple way to create /+ navigate / list / clean up git worktrees.- can be used for more advanced workflows, such as [LLM commitmessages](#llm-commit-messages), or [local merging of worktrees gated onCI-like checks](#local-merging-with-wt-merge)-- also comes with optional QoL features, such as listing branches' CI status or- Claude Code status, or a great [Claude Code statusline](#wt-list-statusline).+- also comes with optional QoL features, such as listing the CI status & the+ Claude Code status for all branches, or a great [Claude Code+ statusline](#wt-list-statusline)....there's no need to use the more advanced features to get the simplerbenefits, and everything is fully compatible with standard git worktrees.@@ -92,8 +94,8 @@ After doing some work:```console$ wt listBranch Status HEAD± main↕ Path Remote⇅ Commit Age Message-@ feature-api + ↑ +3 ↑4 ./repo.feature-api 5b01afca 30m Add API tests-^ main ^| ./repo | b834638e 1d Initial commit+@ feature-api + ↑⇡ +36 -11 ↑4 ./repo.feature-api ⇡3 b1554967 30m Add API tests+^ main ^⇣ ./repo ⇣1 b834638e 1d Initial commit+ fix-auth _ ./repo.fix-auth b834638e 1d Initial commit⚪ Showing 3 worktrees, 1 with changes, 1 ahead@@ -130,7 +132,10 @@ So we use git worktrees: multiple working directories backed by a single reposit## Why Worktrunk?-Git's built-in `worktree` commands give you the primitives but not the lifecycle. Worktrunk bundles creation, navigation, status, and cleanup into simple commands. A few examples:+Git's built-in `worktree` commands offers primitives, but requires the user+to remember worktree's location, and compose commands together. Worktrunk+bundles creation, navigation, status, and cleanup into simple commands. A few+examples:<table><tr>@@ -139,43 +144,70 @@ Git's built-in `worktree` commands give you the primitives but not the lifecycle<th>Plain git</th></tr><tr>+<td>Switch worktrees</td>+<td><pre lang="bash">wt switch feature</pre></td>+<td><pre lang="bash">cd ../repo.feature</pre></td>+</tr>+<tr><td>Create + start Claude</td>-<td><pre lang="bash">wt switch -c feature -x claude</pre></td>+<td><pre lang="bash">wt switch -c -x claude feature</pre>+...or with an <a href="#alias">alias</a>:+<pre lang="bash">+wsc feature+</pre></td><td><pre lang="bash">git worktree add -b feature ../repo.feature main-cd ../repo.feature && claude</pre></td>+cd ../repo.feature+claude</pre></td></tr>+<tr><td>Clean up</td>-<td><pre lang="bash">wt remove feature</pre></td>-<td><pre lang="bash">git worktree remove ../repo.feature+<td><pre lang="bash">wt remove</pre></td>+<td><pre lang="bash">cd ../repo+git worktree remove ../repo.featuregit branch -d feature</pre></td></tr><tr>-<td>Full workflow</td>-<td><pre lang="bash"># after configuring hooks-wt merge</pre></td>-<td><pre lang="bash">git add -A-git reset --soft $(git merge-base HEAD main)-# commit-generation-git diff --staged | llm "msg" | git commit -F --git rebase main-# pre-merge hook-cargo test-cd ../repo && git merge --ff-only feature-git worktree remove ../repo.feature-git branch -d feature-# post-merge hook-cargo install --path .</pre></td>+<td>List worktrees</td>+<td><pre lang="bash">wt list</pre>+...including diffstats & status+</td>+<td><pre lang="bash">git worktree list</pre>+...just branch names & paths+</td>+</tr>+<tr>+<td>List with CI status</td>+<td><pre lang="bash">wt list --full</pre>+...including CI status & diffstat downstream of <code>main</code>, add <code>--branches</code> or <code>--remotes</code> for more+</td>+<td>N/A</td></tr></table>+...and check out examples below for more advanced workflows.+## AdvancedMost Worktrunk users just use the commands above. But I've found these features really helpful too:+### Shell integration++Shell integration lets `wt switch`, `wt merge`, and `wt remove` change+directories:++```console+wt config shell install # Bash, Zsh, Fish+```++Manual setup: `wt config shell --help`.+### Local merging with `wt merge`-`wt merge` handles the full merge workflow: stage, commit, squash, rebase, run hooks, merge, cleanup.+`wt merge` handles the full merge workflow: stage, commit, squash, rebase,+merge, cleanup. Includes [LLM commit messages](#llm-commit-messages),+[project hooks](#project-hooks), and [config](#wt-config)/[flags](#wt-merge)+for skipping steps.<table><tr>@@ -188,13 +220,15 @@ Most Worktrunk users just use the commands above. But I've found these features<td><pre lang="bash">wt merge</pre></td><td><pre lang="bash">git add -Agit reset --soft $(git merge-base HEAD main)-git diff --staged | llm "msg" | git commit -F -+git diff --staged | llm "Write a commit message based on this diff" | git commit -F -git rebase main-cargo test # pre-merge hook+# pre-merge hook+cargo testcd ../repo && git merge --ff-only featuregit worktree remove ../repo.featuregit branch -d feature-cargo install --path . # post-merge hook</pre></td>+# post-merge hook+cargo install --path . </pre></td></tr></table>@@ -211,7 +245,9 @@ command = "llm"args = ["-m", "claude-haiku-4-5-20251001"]```-`wt merge` generates commit messages automatically:+`wt merge` generates commit messages automatically or `wt step commit` runs just the commit step.++For custom prompt templates: `wt config --help`.<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__merge__readme_example_complex.snap — edit source to update -->@@ -264,8 +300,6 @@ test result: ok. 18 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; fin<!-- END AUTO-GENERATED -->-`wt step commit` runs just the commit step. Custom prompt templates: `wt config --help`.-### Project hooksConfigure hooks in `.config/wt.toml`:@@ -355,24 +389,101 @@ All checks passed!See `wt switch --help` and `wt merge --help` for skipping hooks, template variables, security details.-### Shell integration+### Custom Worktree Status-Shell integration lets `wt switch`, `wt merge`, and `wt remove` change-directories:+Add emoji status markers to branches that appear in `wt list`.```console-wt config shell install # Bash, Zsh, Fish+# Set status for current branch+wt config status set "🤖"++# Or use git config directly+git config worktrunk.status.feature-x "💬"```-Manual setup: `wt config shell --help`.+**Status appears in the Status column:**++<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__with_user_status.snap — edit source to update -->++```console+$ wt list+ Branch Status HEAD± main↕ Path Remote⇅ Commit Age Message+@ main ^ ./repo b834638e 1d Initial commit++ feature-api ↑ 🤖 ↑1 ./repo.feature-api 9606cd0f 1d Add REST API endpoints++ review-ui ? ↑ 💬 ↑1 ./repo.review-ui afd3b353 1d Add dashboard component++ wip-docs ?_ ./repo.wip-docs b834638e 1d Initial commit++⚪ Showing 4 worktrees, 2 ahead+```++<!-- END AUTO-GENERATED -->++The custom emoji appears directly after the git status symbols.++<details>+<summary>Automation with Claude Code Hooks</summary>++Claude Code can automatically set/clear emoji status when coding sessions start and end.++When using Claude:++- Sets status to `🤖` for the current branch when submitting a prompt (working)+- Changes to `💬` when Claude needs input (waiting for permission or idle)+- Clears the status completely when the session ends++**How it works:**++- Status is stored as `worktrunk.status.<branch>` in `.git/config`+- Each branch can have its own status emoji+- The hooks automatically detect the current branch and set/clear its status+- Works with any git repository, no special configuration needed++</details>++### `wt select`++Interactive worktree selector with fuzzy search and diff preview. Unix only.++Preview tabs (toggle with `1`/`2`/`3`):++- **Tab 1**: Working tree changes (uncommitted)+- **Tab 2**: History (commits not on main highlighted)+- **Tab 3**: Branch diff (changes ahead of main)++### `wt list statusline`++Single-line status for shell prompts, starship, or editor integrations.++**Claude Code integration** (`--claude-code`): Reads workspace context from+stdin, outputs directory, branch status, and model name.++```text+~/w/myproject.feature-auth !🤖 ±+42 -8 ↑3 ⇡1 ● | Opus+```++<details>+<summary>Claude Code configuration</summary>++Add to `~/.claude/settings.json`:++```json+{+ "statusLine": {+ "type": "command",+ "command": "wt list statusline --claude-code"+ }+}+```++</details>## Tips & patterns-**Alias for new worktree + agent:**+<a id="alias"></a>**Alias for new worktree + agent:**```console-alias wsl='wt switch --create --execute=claude'-wsl new-feature # Creates worktree, runs hooks, launches Claude+alias wsc='wt switch --create --execute=claude'+wsc new-feature # Creates worktree, runs hooks, launches Claude```**Eliminate cold starts** — `post-create` hooks install deps and copy caches.@@ -405,7 +516,7 @@ in terminals with hyperlink support.worktree. Example: `wt switch --create hotfix --base=@` branches from currentHEAD.-## Commands+## Commands Reference<details><summary><strong><code>wt switch [branch]</code></strong> - Switch to existing worktree or create a new one</summary>@@ -1096,96 +1207,6 @@ Global Options:</details>-## Advanced Features--### Custom Worktree Status--Add emoji status markers to branches that appear in `wt list`.--```console-# Set status for current branch-wt config status set "🤖"--# Or use git config directly-git config worktrunk.status.feature-x "💬"-```--**Status appears in the Status column:**--<!-- ⚠️ AUTO-GENERATED from tests/snapshots/integration__integration_tests__list__with_user_status.snap — edit source to update -->--```console-$ wt list- Branch Status HEAD± main↕ Path Remote⇅ Commit Age Message-@ main ^ ./repo b834638e 1d Initial commit-+ feature-api ↑ 🤖 ↑1 ./repo.feature-api 9606cd0f 1d Add REST API endpoints-+ review-ui ? ↑ 💬 ↑1 ./repo.review-ui afd3b353 1d Add dashboard component-+ wip-docs ?_ ./repo.wip-docs b834638e 1d Initial commit--⚪ Showing 4 worktrees, 2 ahead-```--<!-- END AUTO-GENERATED -->--The custom emoji appears directly after the git status symbols.--<details>-<summary>Automation with Claude Code Hooks</summary>--Claude Code can automatically set/clear emoji status when coding sessions start and end.--When using Claude:--- Sets status to `🤖` for the current branch when submitting a prompt (working)-- Changes to `💬` when Claude needs input (waiting for permission or idle)-- Clears the status completely when the session ends--**How it works:**--- Status is stored as `worktrunk.status.<branch>` in `.git/config`-- Each branch can have its own status emoji-- The hooks automatically detect the current branch and set/clear its status-- Works with any git repository, no special configuration needed--</details>--### `wt select`--Interactive worktree selector with fuzzy search and diff preview. Unix only.--Preview tabs (toggle with `1`/`2`/`3`):--- **Tab 1**: Working tree changes (uncommitted)-- **Tab 2**: History (commits not on main highlighted)-- **Tab 3**: Branch diff (changes ahead of main)--### `wt list statusline`--Single-line status for shell prompts, starship, or editor integrations.--**Claude Code integration** (`--claude-code`): Reads workspace context from-stdin, outputs directory, branch status, and model name.--```-~/w/myproject.feature-auth !🤖 ±+42 -8 ↑3 ⇡1 ● | Opus-```--<details>-<summary>Claude Code configuration</summary>--Add to `~/.claude/settings.json`:--```json-{- "statusLine": {- "type": "command",- "command": "wt list statusline --claude-code"- }-}-```--</details>-## FAQ<details>@@ -1203,7 +1224,7 @@ Commands from project hooks and LLM configuration require approval on first run.<!-- ⚠️ AUTO-GENERATED from tests/integration_tests/snapshots/integration__integration_tests__shell_wrapper__tests__readme_example_approval_prompt.snap — edit source to update -->-```+```text🟡 repo needs approval to execute 3 commands:⚪ post-create install:diff --git a/tests/integration_tests/list.rs b/tests/integration_tests/list.rsindex c4db24e0d..87042b75b 100644--- a/tests/integration_tests/list.rs+++ b/tests/integration_tests/list.rs@@ -970,8 +970,9 @@ fn test_list_user_status_with_special_characters() {/// Generate README example: List output for Quick Start narrative////// Shows main + fix-auth + feature-api worktrees (matches the Quick Start flow):+/// - main: behind remote (teammate pushed while we were working)/// - fix-auth: just created, no commits ahead (same as main)-/// - feature-api: where we switched to and did work (commits ahead + staged changes)+/// - feature-api: commits ahead of main and remote, plus staged changes////// Output: tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap#[test]@@ -981,25 +982,76 @@ fn test_readme_example_simple_list() {repo.commit_with_age("Initial commit", DAY);repo.setup_remote("main");+ // Make main behind its remote: push a commit, then reset local+ // (simulates a teammate pushing while we work on feature-api)+ repo.commit_with_age("Teammate's fix", 2 * HOUR);+ let mut cmd = Command::new("git");+ repo.configure_git_cmd(&mut cmd);+ cmd.args(["push", "origin", "main"])+ .current_dir(repo.root_path())+ .output()+ .unwrap();+ // Reset local main back one commit (so it's behind origin/main)+ let mut cmd = Command::new("git");+ repo.configure_git_cmd(&mut cmd);+ cmd.args(["reset", "--hard", "HEAD~1"])+ .current_dir(repo.root_path())+ .output()+ .unwrap();+// Create fix-auth worktree (just created, no work yet - same commit as main)let _fix_auth = repo.add_worktree("fix-auth");// Create feature-api worktree (existing work - we switched here and did work)let feature_api = repo.add_worktree("feature-api");- // feature-api: several commits ahead with staged changes (a morning's work)- repo.commit_with_age_in("Add REST endpoints", 3 * HOUR, &feature_api);- repo.commit_with_age_in("Add authentication middleware", 2 * HOUR, &feature_api);- repo.commit_with_age_in("Add request validation", HOUR, &feature_api);+ // Push feature-api to establish tracking, then make more local commits+ repo.commit_with_age_in("Add REST endpoints", 4 * HOUR, &feature_api);+ let mut cmd = Command::new("git");+ repo.configure_git_cmd(&mut cmd);+ cmd.args(["push", "-u", "origin", "feature-api"])+ .current_dir(&feature_api)+ .output()+ .unwrap();++ // More local commits (ahead of remote)+ repo.commit_with_age_in("Add authentication middleware", 3 * HOUR, &feature_api);+ repo.commit_with_age_in("Add request validation", 2 * HOUR, &feature_api);++ // Create a file with content that we'll modify (to get deletions in HEAD±)+ std::fs::write(+ feature_api.join("validation.rs"),+ "// Request validation\npub fn validate(req: &Request) -> Result<(), Error> {\n if req.body.is_empty() {\n return Err(Error::EmptyBody);\n }\n if req.body.len() > MAX_SIZE {\n return Err(Error::TooLarge);\n }\n if !req.headers.contains_key(\"Authorization\") {\n return Err(Error::Unauthorized);\n }\n Ok(())\n}\n",+ )+ .unwrap();+ let mut cmd = Command::new("git");+ repo.configure_git_cmd(&mut cmd);+ cmd.args(["add", "validation.rs"])+ .current_dir(&feature_api)+ .output()+ .unwrap();repo.commit_with_age_in("Add API tests", 30 * MINUTE, &feature_api);- // Staged changes: a few more files in progress- std::fs::write(feature_api.join("api.rs"), "// WIP: rate limiting\n").unwrap();- std::fs::write(feature_api.join("middleware.rs"), "// WIP: caching\n").unwrap();- std::fs::write(feature_api.join("tests.rs"), "// WIP: edge cases\n").unwrap();+ // Staged changes: new files (additions) + modify existing file (mixed +/-)+ std::fs::write(+ feature_api.join("api.rs"),+ "// Rate limiting implementation\nuse std::time::Duration;\n\npub struct RateLimiter {\n requests_per_second: u32,\n window: Duration,\n}\n\nimpl RateLimiter {\n pub fn new(rps: u32) -> Self {\n Self { requests_per_second: rps, window: Duration::from_secs(1) }\n }\n}\n",+ )+ .unwrap();+ std::fs::write(+ feature_api.join("middleware.rs"),+ "// Caching middleware\nuse std::collections::HashMap;\n\npub struct Cache<T> {\n store: HashMap<String, T>,\n ttl_seconds: u64,\n}\n\nimpl<T> Cache<T> {\n pub fn get(&self, key: &str) -> Option<&T> {\n self.store.get(key)\n }\n}\n",+ )+ .unwrap();+ // Modify validation.rs: remove some lines, add others (creates both + and -)+ std::fs::write(+ feature_api.join("validation.rs"),+ "// Request validation (refactored)\npub fn validate(req: &Request) -> Result<(), ValidationError> {\n validate_body(&req.body)?;\n validate_auth(&req.headers)?;\n Ok(())\n}\n\nfn validate_body(body: &[u8]) -> Result<(), ValidationError> {\n if body.is_empty() { return Err(ValidationError::Empty); }\n if body.len() > MAX_SIZE { return Err(ValidationError::TooLarge); }\n Ok(())\n}\n",+ )+ .unwrap();let mut cmd = Command::new("git");repo.configure_git_cmd(&mut cmd);- cmd.args(["add", "api.rs", "middleware.rs", "tests.rs"])+ cmd.args(["add", "api.rs", "middleware.rs", "validation.rs"]).current_dir(&feature_api).output().unwrap();diff --git a/tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap b/tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snapindex 6b02bab02..493595a03 100644--- a/tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap+++ b/tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap@@ -24,8 +24,8 @@ exit_code: 0----- stderr -----[1mBranch[0m [1mStatus[0m [1mHEAD±[0m [1mmain↕[0m [1mPath[0m [1mRemote⇅[0m [1mCommit[0m [1mAge[0m [1mMessage[0m-@ [1mfeature-api[0m [36m+[39m [2m↑[22m [32m+3[0m [32m↑4[0m [1m./repo.feature-api[0m [2m5b01afca[0m [2m30m[0m [2mAdd API tests[0m-^ main [2m^[22m[2m|[22m ./repo [2m|[0m [2mb834638e[0m [2m1d[0m [2mInitial commit[0m+@ [1mfeature-api[0m [36m+[39m [2m↑[22m[2m⇡[22m [32m+36[0m [31m-11[0m [32m↑4[0m [1m./repo.feature-api[0m [32m⇡3[0m [2mb1554967[0m [2m30m[0m [2mAdd API tests[0m+^ main [2m^[22m[2m⇣[22m ./repo [2m[31m⇣1[0m [2mb834638e[0m [2m1d[0m [2mInitial commit[0m+ [2mfix-auth[0m [2m_[22m [2m./repo.fix-auth[0m [2mb834638e[0m [2m1d[0m [2mInitial commit[0m⚪ [2mShowing 3 worktrees, 1 with changes, 1 ahead[0m