Fun AI Lab

AI coding agents are fundamentally changing how software gets built. Instead of sitting around waiting for an agent to finish refactoring a module, writing tests, or updating dependencies, you can spin up three or four agents to tackle different tasks at the same time.

There’s just one problem: Git wasn’t built for a single developer operating four isolated workspace contexts on one machine simultaneously.

If you try to run multiple autonomous agents inside a single Git repository directory using standard git checkout, chaos follows. Agent A edits files while Agent B runs tests on a different branch, leading to corrupted state, uncommitted file leaks, and build failures.

Git worktrees solve this by giving every task its own isolated working directory while sharing a single underlying .git history. However, native Git worktree commands are notoriously verbose, clunky, and manual.

Enter Worktrunk (max-sixty/worktrunk), an open-source CLI that makes Git worktree management as natural and friction-free as standard Git branches.

---

The Problem: The AI Agent Concurrency Bottleneck

When you delegate work to AI agents, your job shifts from writing every line of syntax to orchestrating workflows. You become a manager directing a fleet of digital engineers.

When you run agents sequentially, your productivity drops:

[Agent 1 Working on Auth] ---> (Wait 5 Mins) ---> [You Review] ---> [Agent 2 Working on UI]

To maximize speed, you want a parallel workflow:

[Agent 1: Auth Feature]   --> Workspace A
[Agent 2: Database Migration] --> Workspace B
[Agent 3: Unit Test Coverage] --> Workspace C

If all three agents run in the same root directory, they overwrite each other’s files. Standard branch switching (git checkout feature-b) changes the files on disk while Agent 1 is actively reading or writing them, causing immediate crashes or corrupted code logic.

Native git worktree commands fix the isolation problem, but managing them manually creates administrative overhead:

# Native Git Worktree creation is verbose and tedious
git worktree add ../my-repo-feature-a -b feature-a
cd ../my-repo-feature-a
npm install # Must manually set up dependencies every time

Worktrunk removes this friction entirely.

---

What is Worktrunk?

Worktrunk is an open-source CLI written in Rust that elevates Git worktrees into a first-class, effortless workflow tool. It abstracts away complex paths, directory tracking, and manual setup commands.

Instead of jumping between disconnected directories across your filesystem, Worktrunk allows you to create, switch, automate, and clean up isolated worktrees using punchy, intuitive CLI commands.

graph TD
    Repo[Main Git Repository Repository] --> Worktrunk[Worktrunk CLI Engine]

    Worktrunk --> WT1[Worktree: feature/auth-fix]
    Worktrunk --> WT2[Worktree: feature/ui-redesign]
    Worktrunk --> WT3[Worktree: bugfix/api-leak]

    WT1 --> Agent1[AI Agent 1: Claude Code]
    WT2 --> Agent2[AI Agent 2: Aider / Codex]
    WT3 --> Dev[Developer: Manual Hotfix]

    subgraph Isolated File Systems
        WT1
        WT2
        WT3
    end

By isolating each worktree while retaining unified Git commit histories, you can launch as many AI agents as your CPU and API limits allow.

---

Core Capabilities & Features

Worktrunk delivers several key capabilities designed to eliminate context-switching drag:

1. Ultra-Simple Workspace Lifecycle

Worktrunk streamlines creation and movement across branches down to brief commands. You can spawn a new feature workspace and jump straight into it without calculating relative directory paths.

2. Workspace Hook Automation

When creating a raw Git worktree, new directories lack untracked assets like node_modules, python virtual environments (.venv), or built binaries. Worktrunk supports configurable hooks that run automatically whenever a new worktree is spawned.

You can configure Worktrunk to instantly copy .env files, run npm install, or set up isolated Python virtual environments the moment a branch workspace opens.

3. Intention-Driven Navigation

Worktrunk keeps track of active worktrees across your project root. Switching between environments, listing active parallel branches, and removing worktrees after merging requires minimal typing.

---

Native Git vs. Git Worktrees vs. Worktrunk

To see why Worktrunk fits AI agent workflows so well, let’s compare standard Git operations with native worktrees and Worktrunk:

Feature / Context	Standard Git (`git branch`)	Native `git worktree`	Worktrunk (`wt`)
Parallel Agent Execution	Impossible (single working dir)	Supported	Supported & Streamlined
Directory Navigation	Same folder on disk	Manual relative paths	Automatic branch targeting
Environment Setup Automation	Preserved across switch	Manual setup per tree	Automated via pre/post hooks
Cleanup Overhead	N/A	Requires manual prune & delete	Single clean command

---

Getting Started with Worktrunk

Worktrunk is packaged as a high-performance CLI binary (wt). Here is how you can install and start using it immediately.

Installation

You can install Worktrunk directly via package managers or binary releases.

# Install via Cargo (Rust package manager)
cargo install worktrunk

# Alternatively, check docs at worktrunk.dev for Homebrew / binary scripts
# Verify installation
wt --version

Core Workflow Commands

Worktrunk reduces complex worktree orchestration down to simple operations:

# 1. Create and switch to a new worktree/branch instantly
wt switch -c feature/add-oauth

# 2. List all active worktrees and their locations
wt list

# 3. Switch between existing agent workspaces seamlessly
wt switch feature/refactor-db

# 4. Remove a worktree and clean up the associated directory when done
wt remove feature/add-oauth

---

Real-World Use Case: Multi-Agent Parallel Coding

Imagine you have three tasks assigned to your sprint today:
1. Fix a CORS header bug in your API layer.
2. Upgrade React dependencies in the frontend directory.
3. Generate unit tests for an internal payment module.

Here is how you execute all three at once using Worktrunk and an AI agent CLI (such as Claude Code or Aider):

# --- Workspace 1: Bugfix ---
wt switch -c fix/cors-headers
# Launch Agent 1 in terminal tab 1
claude "Fix CORS configuration in server.ts to allow localhost:3000"

# --- Workspace 2: Dependency Upgrade ---
# Open terminal tab 2
wt switch -c chore/upgrade-react
# Launch Agent 2 in terminal tab 2
aider --message "Upgrade React to v19 and fix breaking type changes"

# --- Workspace 3: Testing ---
# Open terminal tab 3
wt switch -c test/payment-module
# Launch Agent 3 in terminal tab 3
claude "Generate complete unit test suite for services/payment.ts"

While all three agents execute independently in their own isolated folders, you can jump between tabs, view live diffs, test individual components, and merge completed branches into main without a single file collision.

---

Configuring Automated Setup Hooks

One common frustration with Git worktrees is that non-committed setup files (like .env configuration files or dependencies) aren’t present in new worktrees.

Worktrunk handles this gracefully via configuration hooks. You can set up a local configuration (e.g., in .config/worktrunk.toml or global settings) to automate setup tasks:

# Example Worktrunk Hook Configuration
[hooks]
# Automatically symlink or copy local secret configs into new worktrees
post_create = """
cp ../main/.env .env
npm install
"""

Now, every time you or an AI agent runs wt switch -c <branch>, your dependencies and build tools are ready immediately.

---

Common Myths and Misconceptions

Myth 1: “Git worktrees duplicate my entire project history and waste disk space.”

Fact: Worktrees share the exact same .git folder and object database as your primary repository. The only additional disk space consumed is by the actual working files on disk and local untracked dependencies (like node_modules).

Myth 2: “I can just use `git stash` to let agents work sequentially.”

Fact: git stash forces sequential execution. If Agent A takes 10 minutes to run tests and make changes, you are completely blocked from making progress on Branch B without interrupting Agent A. Worktrees decouple active execution contexts.

Myth 3: “Worktrunk replaces Git branches.”

Fact: Worktrunk uses standard Git branches under the hood. Any worktree created in Worktrunk is fully compatible with standard Git commands, GitHub PRs, and standard team workflows.

---

Actionable Tips for Peak Productivity

1. Pair Worktrunk with Terminal Multiplexers: Use tmux or Zellij alongside Worktrunk. Set up a split window layout where each window represents an active Worktrunk workspace running a dedicated agent process.
2. Automate Heavy Install Steps: If your project takes minutes to build or run npm install, leverage Worktrunk hooks to copy cache directories or use package managers with global caching (pnpm, bun).
3. Clean Up Routinely: When an agent finishes its work and the pull request is merged, run wt remove <branch> to keep your file tree tidy and reclaim local storage.

---

Summary & Next Steps

As developer workflows shift toward managing multiple concurrent AI agents, traditional Git branch switching becomes a bottleneck. Worktrunk eliminates this friction, turning Git worktrees into a fast, fluid tool for parallel execution.

If you are running agents like Claude Code, Cursor, or Aider across multiple tasks, Worktrunk provides the isolation and speed needed to scale your output without repository chaos.

📂 Explore the open-source repository on GitHub: https://github.com/max-sixty/worktrunk