Oleksandr Kuzmenko, EditorPublished 7 min readAI-assisted · editor-reviewed
TL;DR
- Worktrunk eliminates git worktree syntax overhead by addressing checkouts directly through branch names.
- The `-x` flag launches autonomous agents (Claude Code, Codex) inside isolated directories in one step.
- Copy-on-write build cache integration shares `node_modules` and `target` across worktrees on APFS, btrfs, and XFS.
Key facts
- Supported CoW Filesystems
- APFS, btrfs, XFS
- Core Commands
- wt switch, wt list, wt merge, wt remove
- Package Managers
- Homebrew, Cargo, Pacman, Winget (git-wt), Conda, Pixi
The Ergonomic Bottleneck of Parallel Agent Workflows
When running background agents like Claude Code or Codex, engineers frequently orchestrate several independent features in parallel. Using Git's native worktree command requires verbose syntax (git worktree add -b feat ../repo.feat && cd ../repo.feat), manual cleanup steps, and separate dependency installations for every single task.
Worktrunk addresses this workflow problem by condensing multi-step worktree setup into standard branch-like operations through its wt command-line interface.
Instant Execution and Automated Hooks
The primary command for spawning an agent workspace is wt switch. Using the -x execution flag, developers can create a worktree, branch, and start an agent process in a single invocation:
wt switch -x claude -c feature-auth -- 'Add user authentication'
wt switch -x claude -c feature-bugfix -- 'Fix the pagination bug'Arguments passed after -- are handed directly to the target CLI binary. Worktrunk supports post-creation lifecycle hooks to automate background dependency installs (npm install or cargo build) and assigns deterministic ports to local development servers using the hash_port template filter.
Copy-on-Write Build Cache Sharing
Duplicating multi-gigabyte build artifacts across 10 concurrent agent checkouts quickly exhausts SSD storage. Worktrunk implements filesystem-level copy-on-write sharing on APFS (macOS), btrfs, and XFS (Linux). Multiple worktrees share identical node_modules/, target/, or .venv/ directories instantly without triggering cold builds.
Once an agent finishes, wt merge squashes, rebases, merges changes directly into main, and deletes the underlying worktree and branch in the background.
Try it in 2 minutes
brew install worktrunk && wt config shell install
wt switch -x claude -c feature-auth -- 'Add user authentication'When to use
- Use when running multiple background coding agents concurrently on the same Git repository.
- Use when switching frequently between long-running Pull Request reviews and active local development branches.
When NOT to use
- Do not use on legacy filesystems (like FAT32 or standard ext4) if you rely on instant copy-on-write cache sharing.
- Avoid using if your team uses monorepo sparse-checkout tooling with bespoke Git hooks that conflict with worktrees.
What to do today
- Install Worktrunk via `brew install worktrunk` or `cargo install worktrunk` and run `wt config shell install`.
- Configure branch directory templates in your local repository to standardize worktree naming.
- Test running two simultaneous Claude Code tasks using `wt switch -x claude -c <branch> -- '<prompt>'`.
Step names are taken from What to do today.
Step names are taken from What to do today. Install Worktrunk via `brew install worktrunk` or `cargo install worktrunk` and run `wt config shell install`.. Configure branch directory templates in your local repository to standardize worktree naming.. Test running two simultaneous Claude Code tasks using `wt switch -x claude -c <branch> -- '<prompt>'`.
- Install Worktrunk via `brew install worktrunk` or `cargo install worktrunk` and run `wt config shell install`.
- Configure branch directory templates in your local repository to standardize worktree naming.
- Test running two simultaneous Claude Code tasks using `wt switch -x claude -c <branch> -- '<prompt>'`.