What Is Worktrunk? The Beginner's Guide to Git Worktrees for Parallel AI Agents

CodexFuse Team · 2026-11-04T20:13:02.870Z · 11 min read min read

What Is Worktrunk? The Beginner's Guide to Git Worktrees for Parallel AI Agents

If you have been wondering what is worktrunk, here is the short answer: Worktrunk is a command-line tool for managing git worktrees, designed for running AI coding agents in parallel. It is written in Rust, published by Maximilian Roos (max-sixty on GitHub), and licensed as open source under MIT or Apache-2.0. The project's own README describes it in one line: "Worktrunk is a CLI for git worktree management, designed for running AI agents in parallel." As of November 2026 the repo sits near 11,000 stars and is one of the fastest-rising developer tools on GitHub — because it solves the most annoying problem in the agent-coding era: two agents fighting over one checkout. This worktrunk explained guide covers what worktrees are, how Worktrunk differs from plain git worktree, the three core commands, the one-command parallel-agent launch, install routes, hooks, and the real limits to know before you adopt it.

If you are setting up a Linux box to run agents on, start with our VPS hosting guide — a small always-on server is the natural place to park long-running agent worktrees so they keep building while your laptop sleeps.

What Is Worktrunk, Exactly?

Worktrunk (invoked as the wt command) is a Rust CLI that turns git worktrees into something you can address by branch name instead of folder path. A git worktree is a linked copy of your repository checked out on a different branch — same repo, same history, separate working directory — so each worktree can be on its own branch while sharing the underlying git database. That is the Worktrunk git worktrees promise: ordinary git mechanics with branch-name convenience. Worktrunk's README puts the pitch bluntly: "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 & copy-on-write build caches." (github.com/max-sixty/worktrunk, crawled 2026-11-04) The project's current release line is v0.81.0, published around October 20, 2026 — it is still pre-1.0 software, so breaking changes can and do land between releases.

One spelling note that will save you confusion: the tool is Worktrunk, not "work truck" — the automotive phrase already pollutes the exact-phrase search results with vocational-fleet articles. There is no other software product, npm package, or crypto token named Worktrunk; every result for the name points at max-sixty/worktrunk.

What Problem Does Worktrunk Solve?

It solves the collision problem: you have one repo checkout, and you want to run three coding agents on three tasks at once — but an agent's working tree is one shared place, so agent A's refactor lands on top of agent B's half-written feature and everything breaks. The old answers were all bad: serialize the agents (slow), clone the repo three times (wasteful, and the clones drift), or constantly stash-switch (error-prone). Git's own worktree command already fixed the underlying mechanic years ago — one repo, many checked-out working directories — but as the README observes, "even a task as small as starting a new worktree requires typing the branch name three times" with plain git. Worktrunk removes that friction so launching a parallel agent becomes a single command.

How Is Worktrunk Different From Plain git worktree?

Worktrunk does not replace git worktree — it builds on it. So the worktrunk vs git worktree question has a one-line answer: Worktrunk is git worktree, with the friction removed. TechCommune's guide puts it cleanly: "Plain git has the same feature (git worktree), so worktrunk adds convenience, not a new ability: branch-name addressing, a folder naming rule, the shell moving you into the folder, a status list, and a merge that cleans up after itself." (techcommune.org, crawled 2026-11-04) In other words, say it once: Worktrunk is a convenience layer over a real git feature, not a competing version-control system.

The core table above is drawn from the README's own comparison (github.com/max-sixty/worktrunk). The four differences that matter in practice: branch-name addressing — worktrees are addressed by branch name, with paths computed from a configurable template, instead of you remembering folder paths; a dashboard list — wt list shows staged changes, ahead/behind counts, unpushed commits, commit age, commit messages, CI status, and even AI-generated branch summaries, versus git's paths-only list; a one-command merge and cleanup — wt merge commits, squashes, rebases onto the target, fast-forwards, and removes the worktree and branch in the background; and PR checkout — wt switch pr:123 jumps straight to a pull request's branch.

How Do You Install Worktrunk?

The Worktrunk install takes about a minute, in five steps. First, install the binary by your platform's route — all of these are verbatim from the README: Homebrew on macOS or Linux with brew install worktrunk, Cargo with cargo install worktrunk, Arch with sudo pacman -S worktrunk, Windows with winget install max-sixty.worktrunk, or the shell installer with curl --proto '=https' --tlsv1.2 -LsSf https://github.com/max-sixty/worktrunk/releases/download/v0.81.0/worktrunk-installer.sh | sh. Prebuilt tarballs ship on every GitHub release with .sha256 sidecars, and there is a community-maintained conda-forge feedstock. Second, run the shell integration: wt config shell install — this step is mandatory, because as the README states, "Shell integration allows commands to change directories," and without it wt switch cannot cd you into the worktree. Third, confirm Git 2.43 or newer is installed (everydev.ai), which is Worktrunk's minimum. Fourth, on Windows note that the command is installed additionally as git-wt, because wt defaults to Windows Terminal's command. Fifth, run wt list inside any git repo to confirm the setup. Our Git beginner guide is the right refresher if worktrees are your first encounter with anything beyond add/commit/push.

What Are Worktrunk's Core Commands?

The core commands are three: switch, list, and remove. This worktrunk tutorial walks through the ones beginners actually use, and the worktrunk wt switch command is the tool's center of gravity: one command creates the branch, creates the worktree, and cds you into it. To create a worktree for a new branch and jump into it, run wt switch --create feature-auth — the README shows the exact output: "✓ Created branch feature-auth from main and worktree @ ~/repo.feature-auth". To move between existing worktrees, wt switch feat addresses the worktree by branch name (commands that take a branch also accept the worktree's path, per the README). wt switch - jumps back to the previous worktree, like cd -. wt list is the dashboard: staged changes, ahead/behind, unpushed commits, commit age, and CI status per branch, with wt list --full adding CI status and AI-generated summaries per branch. wt select opens an interactive TUI for browsing worktrees with streaming CI status and diff, log, PR, and comment previews. When the branch is done, wt merge main squashes, rebases onto main, fast-forward merges, writes an LLM-generated commit message, and removes the worktree and branch in the background — and for the pull-request workflow, the README's arc is wt step commit, then gh pr create, then wt remove after the PR merges.

How Do You Run Parallel AI Agents With Worktrunk?

You launch each agent inside its own worktree with one command, and the agents never share a working tree. This is the Worktrunk parallel agents pattern in one line: one branch, one worktree, one agent. The README's own example is the whole pattern:

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 flags compose: -c creates the branch and worktree if it does not exist, -x runs a command after switching, and arguments after -- are passed to that command (all verbatim from the README). Because -x accepts any command, the pattern is not Claude-specific — you can launch Codex, Cursor, Gemini, or any other agent the same way. If you are new to the agent this pattern pairs with, our Claude Code beginner guide walks through the first session.

What Are Worktrunk Hooks?

Hooks automate the per-worktree setup you would otherwise do by hand — installing dependencies, copying an .env file, or warming a build cache. The README introduces them as "run commands on create, pre-merge, post-merge, etc," and the docs detail the model: ten hooks cover five lifecycle events — switch, start, commit, merge, and remove — each with a blocking pre- variant (failure aborts the operation) and a background post- variant. (worktrunk.dev/hook, crawled 2026-11-04) You define them in TOML, for example pre-start = "npm install" in the project config (.config/wt.toml, checked into git) or the user config (~/.config/worktrunk/config.toml). Two safety notes, said once: hooks run arbitrary shell commands, so review project hooks before approving them — the first run asks for approval, stored at ~/.config/worktrunk/approvals.toml; and --no-hooks skips hooks entirely on switch, merge, remove, and step commit/squash.

What About Build Caches and Dev Servers?

Worktrunk shares copy-on-write build caches across worktrees, so ten worktrees get target/, node_modules/, and friends without building or copying them — on APFS, btrfs, and XFS filesystems. (github.com/max-sixty/worktrunk, crawled 2026-11-04) The related helper is wt step copy-ignored, which reuses ignored files like node_modules or build caches when a worktree is created. And because every parallel worktree may need its own running server, the hash_port template filter in aliases gives each worktree a unique dev-server port, so the five agents do not fight over port 3000. (worktrunk.dev/extending, crawled 2026-11-04)

Where Does Worktrunk Fit With Other Parallel-Agent Tools?

Worktrunk is the worktree CLI underneath — other tools orchestrate on top of it, and they are never rivals. Cornercase is a terminal-multiplexer product that runs coding agents in parallel, one per git worktree: Cornercase is the orchestrator app, Worktrunk is the worktree CLI underneath — same parallel-agents goal, different products, different layers. Our Agent Relay beginner guide covers the handoff tool whose race mode itself uses worktrees — a different lane (agent-to-agent handoff), never a rival. And our Paradev beginner guide covers the parallel-agents workspace lane, a different interface on the same parallel-coding problem.

Sources

• github.com/max-sixty/worktrunk — README (one-liner, three core commands, README comparison table, install routes verbatim, quick-start output verbatim, agent-launch pattern verbatim, merge behavior, shell-integration requirement, branch-name addressing, copy-on-write caches, hooks intro, author self-claim). Crawled 2026-11-04.
• worktrunk.dev — official docs (hooks: ten hooks, five lifecycle events, pre-/post- variants, TOML config files, first-run approval; extending: aliases, hash_port template filter; tips). Crawled 2026-11-04.
• newreleases.io/project/github/max-sixty/worktrunk/release/v0.81.0 — v0.81.0 release notes (MSRV Rust 1.98). Crawled 2026-11-04.
• trend.ondo.sh/github/r/max-sixty--worktrunk/en.html — repository history snapshot (10,375 stars on 2026-11-03, ~437 stars/day velocity, #3 GitHub daily trending, 83 contributors, 153 releases). Crawled 2026-11-04.
• youraiproject.com/github-trending-history — 10,796 stars same week. Crawled 2026-11-04.
• everydev.ai/tools/worktrunk — Git 2.43+ requirement. Crawled 2026-11-04.
• techcommune.org/docs/timesavers/worktrunk.html — prebuilt tarball layout (wt + git-wt) run-tested on Ubuntu 24.04 with 0.81.0; "convenience, not a new ability" line. Crawled 2026-11-04.
• stork.ai/blog/the-git-worktree-tool-built-for-claude-swarms — parallel-Claude-agents framing; wt step copy-ignored. Crawled 2026-11-04.
• digisoulhub.com/blog/worktrunk-git-worktrees/ — MIT/Apache-2.0 dual license verification. Crawled 2026-11-04.
• clauday.com/article/fa7da135-d0e8-4f80-8e17-be8a2d87133 — author identity (Maximilian Roos, also author of xarray and prql). Crawled 2026-11-04.
• dev.to/arshtechpro/worktrunk-git-worktrees-made-simple-for-parallel-ai-agents-1106 — beginner explainer, 2026-09-19. Crawled 2026-11-04.
• converter.brightcoding.dev/blog/worktrunk-the-revolutionary-git-cli-for-ai-agents — explainer context, ~11 days old. Crawled 2026-11-04.

Frequently Asked Questions

Is Worktrunk free?

Yes. Worktrunk is open source under a dual MIT / Apache-2.0 license — you can install and use it for free, with no license key and no sign-up. (github.com/max-sixty/worktrunk; digisoulhub.com, crawled 2026-11-04)

Does Worktrunk replace git worktree?

No. Worktrunk builds directly on top of git's worktree feature and manages real git worktrees — if you removed Worktrunk, every worktree it created would still be there as an ordinary git worktree. What you get is convenience (branch-name addressing, a status dashboard, one-command merge and cleanup) rather than a new ability. (techcommune.org, crawled 2026-11-04)

Which AI coding agents work with Worktrunk?

Any of them, because the -x flag runs whatever command you give it after switching into the worktree — Claude Code, Codex, Cursor, Gemini, and others all launch the same way. The README's examples use Claude, but nothing in the tool is Claude-specific. (github.com/max-sixty/worktrunk, crawled 2026-11-04)

Do worktrees give me the isolation of separate virtual machines?

No — worktrees are separate working directories of one shared repository on one machine, so agents cannot corrupt each other's files, but they share the kernel, filesystem, and network of the host. If you need VM-level isolation between untrusted agent runs, worktrees are not enough; treat them as collision protection between your own tasks, not a security boundary.

What is the difference between Worktrunk and Cornercase?

They work at different layers: Worktrunk is the worktree-management CLI (create, switch, list, merge worktrees), while Cornercase is a terminal-multiplexer product that orchestrates coding agents in parallel, one per git worktree. You could reasonably run Cornercase on top of worktrees managed by Worktrunk — they are not rivals.