Worktrunk Bot
28399c2ae5
Recovering from a deleted current directory never worked in a bare repository. `recover_from_path` walks up from `$PWD` looking for a `.git` **directory**, and a bare repo has no `.git` entry at all — neither at the bare directory itself nor at any ancestor — so the walk ran to the filesystem root and returned nothing. Every caller then degraded: `wt switch` and the picker surfaced git's raw "cannot resolve CWD" error instead of recovering, and `cwd_removed_hint()` fell back to the bare `Current directory was removed` line with no `wt switch ^` suggestion. Bare repos are a first-class layout here — and their worktrees usually sit *inside* the bare directory, so the walk has nowhere else to land. `try_repo_at` now also accepts a directory that is itself a bare repository, using git's own `is_git_directory` heuristic (a `HEAD` file, an `objects/` directory, a `refs/` directory). The probe is a filesystem check rather than a `Repository::at()` call because `at()` discovers *upward*: asking it whether an arbitrary ancestor is a repository answers for some enclosing repository instead of reporting "not one here". The existing `was_worktree_of` validation is unchanged, so a repository found this way still has to list the deleted path among its worktrees before recovery accepts it. The probe lives in `git::is_bare_repo_dir`, shared with `holds_git_data` in `src/git/repository/worktrees.rs`, which already ended in the same three checks — one home for the shape, so a later correction to it lands once. Verified by temporarily reverting the one-line predicate with the tests in place: `test_recover_from_path_bare_repo_worktree` and `test_try_repo_at_accepts_bare_repo_dir` both fail without it and pass with it. <details><summary>Local test runs</summary> `cargo test --lib git::recover` (23 passed), `cargo test --test integration bare_repository` (37 passed), `cargo test --test integration recover` (1 passed), `cargo fmt --check`, `cargo clippy --lib --all-features` — all clean. One unrelated unit test, `copy::tests::test_copy_dir_recursive_does_not_count_a_non_regular_file`, fails in the tend sandbox with `PermissionDenied` from `UnixListener::bind` — the sandbox blocks `AF_UNIX` sockets. It is green on `main` in CI and untouched here. </details> --------- Co-authored-by: worktrunk-bot <254187624+worktrunk-bot@users.noreply.github.com>
Worktrunk
September 2026: Worktrunk was released at the start of the year, and has quickly become the most popular git worktree manager. It's built with love (there's no slop!). Please let me know any frictions at all; I'm intensely focused on continuing to make Worktrunk excellent, and the biggest help is folks posting problems they perceive.
Worktrunk is a CLI for git worktree management, designed for running AI agents in parallel.
Worktrunk's three core commands make worktrees as easy as branches. Plus, Worktrunk has a bunch of quality-of-life features to simplify working with many parallel changes, including hooks to automate local workflows.
A quick demo:
📚 Full documentation at worktrunk.dev 📚
Context: git worktrees
AI agents like Claude Code and Codex can handle longer tasks without supervision, such that it's possible to manage 5-10+ in parallel. Git's native worktree feature gives each agent its own working directory, so they don't step on each other's changes.
But the git worktree UX is clunky. Even a task as small as starting a new
worktree requires typing the branch name three times: git worktree add -b feat ../repo.feat, then cd ../repo.feat.
Worktrunk makes git worktrees as easy as branches
Worktrees are addressed by branch name; paths are computed from a configurable template. Commands that take a branch also accept the path of the worktree it is checked out in.
Start with the core commands
Core commands:
| Task | Worktrunk | Plain git |
|---|---|---|
| Switch worktrees | wt switch feat |
cd ../repo.feat |
| Create + start Claude | wt switch -c -x claude feat |
|
| Clean up | wt remove |
|
| List with status | wt list |
git worktree list (paths only) |
Expand into the more advanced commands as needed
Workflow automation:
- Hooks — run commands on create, pre-merge, post-merge, etc
- LLM commit messages — generate commit messages from diffs
- Merge workflow — squash, rebase, merge, clean up in one command
- Interactive picker — browse worktrees with live diff and log previews
- Share build caches — ten worktrees get
target/,node_modules/, etc without building or copying them (on APFS, btrfs, and XFS) wt list --full— CI status and AI-generated summaries per branch- PR checkout —
wt switch pr:123to jump straight to a PR's branch - Dev server per worktree —
hash_porttemplate filter gives each worktree a unique port - Aliases & per-branch variables — custom
wt <name>commands and branch-scoped state for hook templates - ...and lots more
Multiple parallel agents, same simple commands:
Install
Homebrew (macOS & Linux):
brew install worktrunk && wt config shell install
Shell integration allows commands to change directories.
Cargo:
cargo install worktrunk && wt config shell install
Windows & other
Windows. wt defaults to Windows Terminal's command, so Winget additionally installs Worktrunk as git-wt to avoid the conflict:
winget install max-sixty.worktrunk
git-wt config shell install
Alternatively, disable Windows Terminal's alias (Settings → Apps → Advanced app settings → App execution aliases → "Terminal"/"Terminal Preview") to use wt directly.
Free code signing provided by SignPath.io, certificate by SignPath Foundation — policy.
Arch Linux:
sudo pacman -S worktrunk && wt config shell install
Conda / Pixi (community-maintained feedstock):
conda install -c conda-forge worktrunk && wt config shell install
Or with Pixi: pixi global install worktrunk && wt config shell install.
Quick start
Create a worktree for a new feature:
$ wt switch --create feature-auth
✓ Created branch feature-auth from main and worktree @ ~/repo.feature-auth
This creates a new branch and worktree, then switches to it. Do your work, then check all worktrees with wt list:
$ wt list
Branch Status HEAD± main↕ main…± Remote⇅ Commit Age Message
@ feature-auth + ↑ +27 -8 ↑1 +31 4bc72dc 2h Add authenticati…
^ main ^⇡ ⇡1 0e631ad 1d Initial commit
○ Showing 2 worktrees, 1 with changes, 1 ahead, hidden: Path
The @ marks the current worktree. + means staged changes, ↑1 means 1 commit ahead of main, ⇡ means unpushed commits.
When done, either:
PR workflow — commit, push, open a PR, merge via GitHub/GitLab, then clean up:
wt step commit # commit staged changes
gh pr create # or glab mr create
wt remove # after PR is merged
Local merge — squash, rebase onto main, fast-forward merge, clean up:
$ wt merge main
◎ Generating commit message and committing changes... (2 files, +53, no squashing needed)
Add authentication module
✓ Committed changes @ a1b2c3d
◎ Merging 1 commit to main @ a1b2c3d (no rebase needed)
* a1b2c3d Add authentication module
auth.rs | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
lib.rs | 2 ++
2 files changed, 53 insertions(+)
✓ Merged to main (1 commit, 2 files, +53)
◎ Removing feature-auth worktree & branch in background (same commit as main, _)
○ Switched to worktree for main @ ~/repo
For parallel agents, create multiple worktrees and launch an agent in each:
wt switch -x claude -c feature-a -- 'Add user authentication'
wt switch -x claude -c feature-b -- 'Fix the pagination bug'
wt switch -x claude -c feature-c -- 'Write tests for the API'
The -x flag runs a command after switching; arguments after -- are passed to it. Configure post-start hooks to automate setup (install deps, start dev servers).
Next steps
- Learn the core commands:
wt switch,wt list,wt merge,wt remove - Set up hooks for automated setup
- Explore LLM commit messages, interactive picker, Claude Code integration, CI status & PR links
- Browse tips & patterns for recipes: aliases, dev servers, databases, agent handoffs, and more
- Extending Worktrunk — customize workflows with hooks & aliases
- Run
wt --helporwt <command> --helpfor quick CLI reference
Further reading
- Claude Code: Best practices for agentic coding — Anthropic's official guide, including the worktree pattern
- Shipping faster with Claude Code and Git Worktrees — incident.io's workflow for parallel agents
- Git worktree pattern discussion — Community discussion in the Claude Code repo
- @DevOpsToolbox's video on Worktrunk
- git-worktree documentation — Official git reference
Contributing
- ⭐ Star the repo
- Tell a friend about Worktrunk
- Open an issue — feedback, feature requests, even a small friction or imperfect user message, or a worktree pain not yet solved
- Share: X · Reddit · LinkedIn
Running the tests
cargo test
The shell integration tests need bash, zsh, fish, nushell, and pwsh, plus jq:
cargo test --test integration --features shell-integration-tests
📚 Full documentation at worktrunk.dev 📚