Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: Update README for clarity and content
Maximilian Roosb297e1608ab0
diff --git a/README.md b/README.mdindex 373db9bdc..934a57a2b 100644--- a/README.md+++ b/README.md@@ -21,24 +21,24 @@ goal is to make spinning up a new AI "developer" for a task feel as routine as## December 2025 Project StatusI'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+this week. It's built with love (there's no slop!). If social proof is helpful:+I also created [PRQL](https://github.com/PRQL/prql) (10k stars) and am amaintainer of [Xarray](https://github.com/pydata/xarray) (4k stars),[Insta](https://github.com/mitsuhiko/insta), &[Numbagg](https://github.com/numbagg/numbagg).-Currently, Worktrunk:+I'd recommend:-- simplifies standard worktree workflows — an easier way to create / navigate /- list / clean up git worktrees.-- can be used for more advanced workflows, such as [LLM commit+- **starting with Worktrunk as a simpler & better `git worktree`**: create / navigate /+ list / clean up git worktrees with ease+- **later using the more advanced features if you find they resonate**: there's+ lots for the more ambitious, such as [LLM commitmessages](#llm-commit-messages), or [local merging of worktrees gated on- CI-like checks](#local-merging-with-wt-merge). It 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](#statusline-integration).--I'd recommend starting with it as a simple & better `git worktree`, and then-using the more advanced features if you find they resonate.+ CI-like checks](#local-merging-with-wt-merge), or [fzf-like selector ++ preview](#interactive-worktree-picker). And QoL features, such as listing the+ CI status & the Claude Code status for all branches, or a great [Claude Code+ statusline](#statusline-integration). But they're not required to get value+ from the tool.## Demo@@ -110,22 +110,20 @@ $ wt remove## Why git worktrees?-Parallel agents need isolated working directories that share one Git history.--We can get that a few ways:+We have a few options for working with multiple agents:+- one working tree with many branches — agents step on each other, can't use git+ for staging & committing- multiple clones — slow to set up, drift out of sync-- one working tree with many branches — constant stashing, rebasing, and conflict risk- git worktrees — multiple directories backed by a single `.git` directory-So we use git worktrees: multiple working directories backed by a single repository.+So we use git worktrees! But then...## Why Worktrunk?-Git's built-in `worktree` commands offer primitives, but require the user to-remember worktrees' locations, and compose git & `cd` commands together.-Worktrunk bundles creation, navigation, status, and cleanup into simple-commands. A few examples:+Git's built-in `worktree` commands require remembering worktrees' locations, and+composing git & `cd` commands together. In contrast, Worktrunk bundles creation,+navigation, status, and cleanup into simple commands. A few examples:<table><tr>@@ -182,7 +180,7 @@ Many Worktrunk users will just use the commands above. For more:### LLM commit messagesWorktrunk can invoke external commands to generate commit messages.-[llm](https://llm.datasette.io/) is recommended.+[llm](https://llm.datasette.io/) from [**@simonw**](https://github.com/simonw) is recommended.Add to user config (`~/.config/worktrunk/config.toml`):@@ -222,8 +220,8 @@ or `--no-verify` to skip hooks entirely. Configure in `.config/wt.toml`:# Tests and lints before merging (blocks on failure)[pre-merge]-"test" = "uv run pytest""lint" = "uv run ruff check"+"test" = "uv run pytest"```Example output:@@ -344,8 +342,8 @@ $ wt list<!-- END AUTO-GENERATED -->-- `🤖` — Claude is working (processing a prompt)-- `💬` — Claude is idle or waiting for input+- `🤖` — Claude is working+- `💬` — Claude is waiting for input**Install the plugin:**@@ -369,7 +367,7 @@ git config worktrunk.status.feature "💬" # Direct git config### Interactive Worktree Picker-`wt select` opens a fuzzy-search worktree picker with diff preview. Unix only.+`wt select` opens a fzf-like fuzzy-search worktree picker with diff preview. Unix only.Preview tabs (toggle with `1`/`2`/`3`):@@ -380,7 +378,11 @@ Preview tabs (toggle with `1`/`2`/`3`):### Statusline Integration`wt list statusline` outputs a single-line status for shell prompts, starship,-or editor integrations.+or editor integrations[^1].++[^1]:+ Currently this grabs CI status, so is too slow to use in synchronous+ contexts. If a faster version would be helpful, please add an Issue.**Claude Code** (`--claude-code`): Reads workspace context from stdin, outputsdirectory, branch status, and model.