The Problem
Managing many concurrent Git worktrees is cumbersome: creating a worktree requires multiple commands, switching directories is manual, and cleaning up involves both git worktree remove and branch deletion. When dozens of AI agents operate in parallel, this friction multiplies, leading to wasted cycles and higher risk of conflicts.
What This Does
worktrunk provides a thin CLI that treats worktrees like branches. Core commands live in src/cli/ and src/commands/:
wt switch <branch> – creates (if needed) and cd‑s into a worktree (src/commands/worktree/mod.rs). wt list – shows worktrees with status, built on the list module (src/commands/list/). wt remove – deletes the current worktree and its branch (src/commands/worktree/remove.rs).
Configuration is driven by a TOML template (.config/wt.toml) that maps a branch name to a directory path, making the path deterministic and reproducible. Hooks (src/cli/hook.rs and src/commands/hookcommands.rs) let users run arbitrary scripts (e.g., start Claude, run tests) automatically after a worktree is created or switched.
Documentation is extensive: the docs/ folder contains the full site (docs/templates/.html, docs/content/*.md), and the README lists the core workflow with screenshots.
How To Use It
Setup
Build and install the CLI locally cargo install --path . Or run directly without installing cargo run --bin worktrunk -- <args>
The presence of Cargo.toml and Cargo.lock confirms a standard Rust build.
Configuration
Create or edit the user config (example in dev/config.example.toml): .config/wt.toml pathtemplate = "{reporoot}/{branch}"
The file is read by src/cli/config.rs.
Running it
Switch to (or create) a worktree for branch feat-x wt switch feat-x
Create and launch Claude automatically (hook defined in .config/wt.toml or via CLI flag) wt switch -c -x claude feat-x
List all worktrees with Git status
wt list
Remove the current worktree and its branch
wt remove
All commands resolve to functions in src/commands/, e.g., switch → src/commands/handleswitch.rs, list → src/commands/list/mod.rs.
Real‑World Use
A CI pipeline that runs multiple autonomous agents can spin up isolated environments with:
Agent A
wt switch -c -x claude agent-a Agent B wt switch -c -x claude agent-b After work is done wt remove # executed by each agent in its own worktree
Each agent works in its own directory (repo/agent-a, repo/agent-b) without stepping on each other, and the hooks automatically start the appropriate LLM client.
Code Health & Issues
Low – CI configured – .github/workflows/ci.yaml runs cargo test and benchmarks. Low – Test coverage – 4 test files (src/commands/list/spacing_test.rs etc.) exist, but many core modules lack direct unit tests (e.g., src/commands/worktree/mod.rs). Medium – Hook safety – Hooks execute external scripts (src/cli/hook.rs) without sandboxing; a malicious hook could run arbitrary code. Low – Documentation depth – docs/ provides comprehensive site generation, but the README lacks a quick‑start for non‑Rust users; a short “install via cargo” section would improve onboarding. Low – Platform assumptions – The CLI calls out to the system git binary; no fallback or mock is provided, which could break on minimal containers.
No obvious licensing issues (MIT in LICENSE), secrets are absent, and the repository includes a lockfile (Cargo.lock) and a pre‑commit config.
The Bottom Line
worktrunk delivers a practical abstraction over Git worktrees, lowering friction for parallel AI‑agent workflows. The codebase is well‑structured, CI‑protected, and documented, though core functionality would benefit from broader test coverage and tighter hook sandboxing. Teams that already use Rust and need to manage dozens of concurrent worktrees will find it immediately valuable; smaller or non‑Rust environments may need additional onboarding effort.