Worktrunk: The Revolutionary Git CLI for AI Agents

Struggling with clunky git worktrees while running multiple AI agents? You're not alone. Developers worldwide are abandoning complex shell scripts for a sleek, powerful solution that transforms parallel development. Worktrunk slashes setup time, eliminates context switching, and makes worktrees as intuitive as branches. Ready to 10x your AI agent workflow? Let's dive deep into the tool that's redefining modern Git operations.

This comprehensive guide reveals everything you need to master Worktrunk: from core commands that replace tedious typing to advanced automation hooks that orchestrate entire development pipelines. You'll discover real code examples, pro tips from the creator, and exactly why this Rust-powered CLI became the fastest-growing git worktree manager in 2026. Whether you're managing 5 Claude agents or coordinating complex feature branches, this article delivers the technical depth to revolutionize your workflow.

What Is Worktrunk?

Worktrunk is a lightning-fast command-line interface built specifically for git worktree management in the age of AI-driven development. Created by max-sixty and released in March 2026, this Rust-powered tool addresses a critical pain point: scaling parallel AI agents without the friction of Git's native worktree UX.

Git worktrees allow developers to check out multiple branches simultaneously in separate directories—essential when Claude Code or GitHub Copilot handles long-running tasks independently. However, the native experience demands repetitive typing: branch names three times just to create a worktree, manual directory navigation, and complex cleanup sequences. Worktrunk eliminates this cognitive overhead by treating worktrees as first-class citizens addressed by branch name, not path.

The tool exploded in popularity because it arrived at the perfect moment. AI agents evolved from simple autocomplete to autonomous developers capable of managing entire feature implementations. Developers suddenly needed to orchestrate 5-10+ agents concurrently without filesystem conflicts. Worktrunk's three core commands—switch, list, and remove—reduce 10+ line shell sequences into single, memorable operations. Built with performance and developer experience as primary design goals, it processes worktree operations in milliseconds while providing rich status visualization that plain Git simply cannot match.

Key Features That Transform Your Workflow

Worktrunk packs powerful capabilities into an elegant, minimalist interface. Here's what makes it indispensable for modern development teams.

Branch-Centric Addressing

Forget paths. Worktrunk computes worktree locations from configurable templates automatically. Type wt switch feat and you're instantly in repo.feat/ without memorizing directory structures. This path templating system adapts to any project layout, eliminating the mental mapping between branches and filesystem locations.

Three Core Commands

The entire workflow revolves around switch, list, and remove—intentionally mirroring branch operations. wt switch creates, navigates, and activates worktrees. wt list displays a rich dashboard showing staged changes (+), unpushed commits (⇡), and behind-main status (↕). wt remove cleans up both worktree and branch in one stroke. This consistency reduces learning curves to minutes.

AI Agent Integration

The -x flag executes commands post-switch, perfect for launching Claude directly into new worktrees. Combine with -c to create branches on-the-fly: wt switch -c -x claude feat spawns a worktree and agent in one line. Parallel agent orchestration becomes trivial—launch multiple agents across isolated worktrees without shell script complexity.

Advanced Workflow Automation

Hooks trigger commands on create, pre-merge, post-merge, enabling automated dependency installation or test server startup. LLM commit messages generate descriptive commits from diffs automatically. The merge workflow squashes, rebases, and cleans up in a single command. An interactive picker previews live diffs and logs during switching. Build cache copying shares target/, node_modules/, and other directories between worktrees, eliminating cold starts.

Rich Status Visualization

wt list renders a compact table showing branch names, staged/unstaged changes, commit deltas against main, remote sync status, commit hashes, age, and messages. Symbols like @ (current worktree), ^ (main branch), and ○ (summary stats) provide instant situational awareness across dozens of worktrees.

Shell Integration & Performance

Shell hooks enable directory changes from commands, maintaining seamless navigation. Written in Rust, Worktrunk executes operations in milliseconds while consuming minimal resources. The MIT-licensed codebase welcomes contributions, with comprehensive CI/CD and codecov integration ensuring reliability.

Real-World Use Cases Where Worktrunk Shines

1. Parallel AI Agent Orchestration

You're managing five Claude agents simultaneously—one implements authentication, another fixes pagination, while others write tests and refactor APIs. Worktrunk creates isolated worktrees for each agent in seconds: wt switch -x claude -c feature-auth -- 'Add OAuth2 flow'. Agents work independently without filesystem conflicts. The -x flag launches Claude directly, passing the task description. When agents complete work, wt list shows all changes across branches at a glance, and wt merge main integrates each feature sequentially without manual rebasing.

2. Rapid Multi-Feature Development

A product manager drops three urgent features on your desk. Instead of stashing changes or juggling branches, you spawn three worktrees: wt switch -c payment-gateway, wt switch -c email-templates, wt switch -c admin-dashboard. Each gets its own directory (repo.payment-gateway/, etc.), dependencies, and build caches. You context-switch between them with wt switch payment-gateway—no cd commands or path memorization. Worktrunk's build cache copying shares compiled artifacts, so each worktree starts warm.

3. Bug Fix Isolation & Hotfixing

Production alerts fire while you're deep in feature development. wt switch -c hotfix/critical-bug creates a clean worktree from main in repo.hotfix-critical-bug/. You fix the issue, run wt merge main to squash and fast-forward, then wt remove cleans everything up. Your original feature worktree remains untouched. This isolation guarantees that emergency fixes don't contaminate in-progress development.

4. Code Review & Testing Across Versions

Reviewing a colleague's PR requires testing against multiple dependency versions. Worktrunk lets you create worktrees for each test scenario: wt switch -c test/node-18, wt switch -c test/node-20. Configure post-create hooks to automatically install correct Node versions. Switch between test environments instantly, run validation suites, then remove worktrees when done. The interactive picker (wt switch with no arguments) shows live diffs, helping you understand changes before switching.

5. Documentation & Experimentation Sprints

Writing documentation while experimenting with API changes demands separate contexts. Worktrunk maintains distinct worktrees for docs, experiments, and stable code. Use LLM commit messages to auto-generate descriptive commits: wt step commit analyzes your diff and writes commit messages via Claude. This keeps experimental branches clean without manual commit message crafting.

Step-by-Step Installation & Setup Guide

Getting Worktrunk running takes under two minutes. Choose your installation method based on your platform.

macOS & Linux (Homebrew)

The fastest path for Unix systems:

brew install worktrunk && wt config shell install

This installs the binary and configures shell integration automatically. The wt config shell install command adds hooks to your .bashrc, .zshrc, or .fish config, enabling directory changes from Worktrunk commands.

Cross-Platform (Cargo)

For Rust developers or non-Homebrew systems:

cargo install worktrunk && wt config shell install

Cargo fetches the latest stable release from crates.io. Post-installation, run shell integration setup to enable seamless navigation.

Windows (Winget)

Windows requires special handling due to wt conflicting with Windows Terminal:

winget install max-sixty.worktrunk
git-wt config shell install

Worktrunk installs as git-wt to avoid conflicts. Alternatively, disable Windows Terminal's alias via Settings → Privacy & security → For developers → App Execution Aliases → disable "Windows Terminal" to use wt directly.

Arch Linux (AUR)

For Arch users, install via AUR helper:

paru worktrunk-bin && wt config shell install

Post-Installation Configuration

Verify installation:

wt --version

Configure your worktree path template (optional, defaults to ../repo.{branch}):

wt config set path_template "../worktrees/{branch}"

Set up hooks for your project:

cd your-project
wt hook set post-create "npm install && npm run dev"

This automation runs every time you create a worktree, eliminating manual setup repetition.

REAL Code Examples from the Repository

Let's examine actual Worktrunk commands from the README, breaking down each operation's power and nuance.

Example 1: Creating and Switching to a Feature Worktree

$ wt switch --create feature-auth
✓ Created branch feature-auth from main and worktree @ repo.feature-auth

What happens: The --create flag (shorthand -c) tells Worktrunk to create the branch feature-auth from main if it doesn't exist. Worktrunk then generates the worktree path using its template (default: ../repo.feature-auth), initializes the worktree, and immediately switches your shell to that directory thanks to shell integration. The @ symbol in output indicates your current location. This single command replaces:

git checkout -b feature-auth  # Create branch
git worktree add -b feature-auth ../repo.feature-auth  # Create worktree
cd ../repo.feature-auth  # Navigate

Example 2: Rich Status Dashboard

$ wt list
  Branch        Status        HEAD±    main↕  Remote⇅  Commit    Age   Message
@ feature-auth  +   –      +53                         0e631add  1d    Initial commit
^ main              ^⇡                         ⇡1      0e631add  1d    Initial commit

○ Showing 2 worktrees, 1 with changes, 1 column hidden

Decoding the symbols:

• @ = Current worktree you're in
• ^ = Main branch worktree
• + = Staged changes present
• – = Unstaged changes present
• +53 = 53 lines added vs main
• ⇡ = Unpushed commits ahead of remote
• ⇅ = Behind/ahead of remote
• ○ = Summary footer

This compact visualization shows branch state, diff stats, sync status, commit metadata, and age—all in one glance. No need for git status, git diff --stat, and git log across multiple directories.

Example 3: AI Agent Orchestration

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'

Breaking down the flags:

• -x claude = Execute claude command after switching
• -c = Create branch if missing
• -- = Separator; everything after becomes arguments to the executed command

Each line spawns a new worktree, launches Claude with a specific task, and runs it in isolation. The agents work in parallel without stepping on each other's changes. Scaling from 1 to 10 agents requires only copying the line and changing the branch name and task.

Example 4: Complete Merge Workflow

$ 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

The magic: wt merge main orchestrates an entire sequence:

1. Auto-commits staged changes using LLM-generated messages
2. Squashes if multiple commits exist
3. Rebases onto main if needed
4. Fast-forward merges to main
5. Removes the worktree and branch
6. Switches back to main

This one-command workflow replaces 6+ Git operations and prevents the common mistake of forgetting to delete merged branches.

Example 5: Hook-Automated Setup

wt hook set post-create "npm install && npm run dev"

Automation power: This hook runs every time you create a worktree. When you execute wt switch -c new-feature, Worktrunk automatically installs dependencies and starts the development server. For AI agents, combine with -x to launch a fully-configured environment: wt switch -c agent-task -x claude. The agent starts in a ready-to-code worktree with all dependencies installed.

Advanced Usage & Best Practices

Hook Composition for Complex Workflows

Chain multiple hooks to create sophisticated automation. Set post-create to install dependencies and pre-merge to run tests:

wt hook set post-create "cargo build --release"
wt hook set pre-merge "cargo test --all-features"

This ensures every worktree is build-ready and prevents merging broken code.

Cache Sharing Strategies

Use build cache copying to share compiled artifacts:

wt config set cache_dirs "target,node_modules,.venv"

When creating worktrees, Worktrunk symlinks or copies these directories, reducing build times from minutes to seconds. This is critical for Rust projects with heavy compilation or Node.js apps with large node_modules.

Zellij Tab Management

The README shows Worktrunk integrated with Zellij for terminal multiplexing. Create a layout that spawns multiple worktrees in separate tabs:

zellij --layout worktrunk-layout.kdl

Inside the layout, use wt switch -x to launch different agents per tab, creating a mission control dashboard for parallel development.

Naming Conventions for Scale

Adopt prefixes for worktree types:

• feature/ for new features
• hotfix/ for production fixes
• agent/ for AI agent tasks
• exp/ for experiments

This keeps wt list organized when managing 20+ worktrees.

Interactive Picker for Navigation

Run wt switch without arguments to launch the interactive picker. Use arrow keys to browse worktrees with live diff previews. This beats tab-completion or remembering branch names when worktree count grows.

Comparison with Alternatives

Why choose Worktrunk over other solutions?

Verdict: While plain Git worktrees provide the foundation, Worktrunk adds the developer experience layer that makes parallel workflows practical at scale. Alternative plugins offer fragments of functionality, but none match Worktrunk's cohesive, AI-agent-first design.

Frequently Asked Questions

What are git worktrees and why do I need them?

Git worktrees let you check out multiple branches simultaneously in separate directories. They're essential for parallel AI agents because each agent gets its own working directory, preventing file conflicts when multiple agents modify code concurrently.

How is Worktrunk different from just using git branches?

Branches share a single working directory—you must stash changes to switch. Worktrunks provide isolated directories per branch, allowing true parallel development. Worktrunk makes managing these directories as easy as branches.

Can I use Worktrunk without AI agents?

Absolutely! While designed for AI agents, Worktrunk excels at any parallel development: multi-feature work, hotfix isolation, testing across versions, and code reviews. The core value is simplifying git worktrees for humans too.

Does Worktrunk work on Windows?

Yes! Install via winget install max-sixty.worktrunk. By default, Worktrunk uses git-wt to avoid conflicts with Windows Terminal's wt command. Disable the Terminal alias to use wt directly.

Will Worktrunk slow down my Git operations?

No—it speeds them up. Written in Rust, Worktrunk adds negligible overhead. Build cache copying actually accelerates compilation by sharing artifacts between worktrees.

How do hooks work? Can I customize them?

Hooks are shell commands that run at lifecycle events (create, pre-merge, post-merge). Set them per-project: wt hook set post-create "your-command". Use them to install dependencies, run linters, or start dev servers automatically.

What happens if I delete a worktree manually?

Worktrunk tracks worktrees in Git's metadata. If you rm -rf a worktree directory, run wt list --prune to clean up stale entries. Worktrunk's remove command handles cleanup safely, deleting both worktree and branch.

Conclusion: Why Worktrunk Belongs in Your Toolkit

Worktrunk isn't just another Git wrapper—it's a paradigm shift for developers navigating the AI-agent era. By reducing worktree operations from multi-command sequences into intuitive, branch-centric commands, it removes the friction that made parallel development painful. The Rust-powered performance, rich status visualization, and deep automation hooks create an experience that feels native to Git while adding superpowers Git never had.

What sets Worktrunk apart is its opinionated focus on real workflows. The -x flag for agent launching, LLM commit message generation, and one-command merge workflows aren't gimmicks—they're solutions to daily frustrations discovered through intense dogfooding by its creator. The result is a tool that scales from solo developers managing personal projects to teams orchestrating fleets of AI agents.

My take? If you're not using worktrees yet, Worktrunk makes the learning curve trivial. If you are, it will save you hours weekly. The MIT license and active development mean it's safe for any project, and the comprehensive documentation at worktrunk.dev ensures you'll never feel lost.

Ready to transform your parallel development?

🚀 Install Worktrunk today → Star the repo → Share your workflow wins with the community!

The future of development is parallel. Worktrunk ensures you're equipped to thrive in it.