claudekit / tools / worktrunk
[ Tool · Development ]

Worktrunk

A CLI for git worktree management, designed for running AI agents in parallel. Worktrees are addressed by branch name, and `wt switch -c -x claude feat` creates a worktree and starts Claude Code in it. The Claude Code plugin adds activity tracking in `wt list` and routes the worktrees agents create through Worktrunk.

max-sixty/worktrunk ·updated
$ brew install worktrunk && wt config shell install copy

An open source project by Maximilian Roos (max-sixty/worktrunk, MIT OR Apache-2.0).

Why it matters

AI agents like Claude Code and Codex can handle longer tasks without supervision, such that it’s possible to manage 5-10+ in parallel. Git’s native worktree feature gives each agent its own working directory, so they don’t step on each other’s changes.

But the git worktree UX is clunky. Even a task as small as starting a new worktree requires typing the branch name three times: git worktree add -b feat ../repo.feat, then cd ../repo.feat. Worktrunk addresses worktrees by branch name and computes paths from a configurable template, so its core commands make worktrees as easy as branches.

Core commands

TaskWorktrunkPlain git
Switch worktreeswt switch featcd ../repo.feat
Create + start Claudewt switch -c -x claude featgit worktree add -b feat ../repo.feat && cd ../repo.feat && claude
Clean upwt removecd ../repo && git worktree remove ../repo.feat && git branch -d feat
List with statuswt listgit worktree list (paths only)

Workflow automation

  • Hooks

    Run commands on create, pre-merge, post-merge, and more. For example, install dependencies in pre-start, start a dev server in the background with post-start, and run tests in pre-merge. Project hooks (.config/wt.toml) require approval; user hooks do not.

  • LLM commit messages

    Worktrunk generates commit messages by building a templated prompt and piping it to an external command. This integrates with wt merge, wt step commit, and wt step squash, and the docs include a Claude Code setup that runs claude -p with Haiku.

  • Merge workflow

    wt merge main squashes, rebases onto main, fast-forward merges, and cleans up in one command. For a PR workflow, commit with wt step commit, open the PR, and run wt remove after it is merged.

  • Share build caches

    Ten worktrees get target/, node_modules/, etc without building or copying them. Files are reflinked where the filesystem supports it (APFS, btrfs, XFS, ReFS); the docs cite a Rust first build dropping from ~68s to ~3s.

  • wt list --full and the interactive picker

    CI status and AI-generated summaries per branch, plus a picker that browses worktrees with streaming CI status and diff, log, PR and comment previews.

  • More

    wt switch pr:123 jumps straight to a PR’s branch, the hash_port template filter gives each worktree a unique dev server port, and aliases and per-branch variables add custom wt <name> commands and branch-scoped state.

Claude Code plugin

Install with wt config plugins claude install. The plugin provides:

  • Configuration skill (/worktrunk) — helps set up LLM-generated commit messages, project hooks, and worktree path templates, and fix shell integration issues. Claude Code is designed to load the skill automatically when it detects worktrunk-related questions.
  • Activity tracking — status markers in wt list: 🤖 means the agent is working, 💬 means it is waiting or idle.
  • Worktree isolation — when Claude Code agents run in isolated worktrees (isolation: "worktree"), the plugin’s WorktreeCreate and WorktreeRemove hooks route this through wt switch --create and wt remove, so agent-created worktrees get Worktrunk’s naming conventions, hooks, and lifecycle management.
  • /wt-switch-create skill — starts a task in a fresh worktree without leaving the session.
  • /wt-diff pane — opens a pane beside the conversation that lists the worktrees the session has worked in, with the selected one’s diff below.

Separately, setting wt list statusline --format=claude-code as the statusLine command in ~/.claude/settings.json shows worktree status, model, context usage, and rate-limit pace in the Claude Code statusline.

How to use

# Install (macOS & Linux)
brew install worktrunk && wt config shell install

# Create a worktree for a new feature
wt switch --create feature-auth

# Check all worktrees
wt list

# When done, merge to main and clean up
wt merge main

For parallel agents, create multiple worktrees and launch an agent in each. The -x flag runs a command after switching; arguments after -- are passed to it.

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'

Notes

  • Shell integration — run wt config shell install after installing so commands can change directories.
  • Windows naming conflict — wt defaults to Windows Terminal’s command. Use the git-wt name Winget installs, or disable Windows Terminal’s app execution alias.
  • Filesystems without reflink — on ext4 and NTFS, build caches are copied in full.
  • /wt-diff pane requirement — the pane needs a Claude Code release that loads plugin hooks modules; earlier releases load the rest of the plugin without it.
  • LLM commit setup requirement — the documented claude -p ... --safe-mode command requires Claude Code ≥ 2.1.169.
  • Docs — full documentation is at worktrunk.dev, and the Claude Code integration is covered in Agent Integration.
§ 7

See also

same category · curated
[01]
[MCP] ARTEMIS · ARTEMIS turns natural-language instructions into reliable Android automation. Its native MCP server lets Claude Code drive real devices and emulators, run test workflows, and collect screenshots and Logcat output, while ARTEMIS's own agent performs the on-device steps in the background.
tool · claudekit.io / tools / artemis
[02]
[Tool] Claude Quickstarts · A collection of projects designed to help developers quickly get started with building deployable applications using the Claude API. Runnable quickstarts cover a customer support agent, a financial data analyst, computer use, browser automation, and Claude Managed Agents apps for Slack, Linear, Sentry, and MCP. Some quickstarts let Claude Code drive the setup.
tool · claudekit.io / tools / claude-quickstarts
[03]
[Plugin] Superpowers · A complete software development methodology for your coding agents, built on composable skills that enforce TDD, systematic debugging, and plan-driven execution.
tool · claudekit.io / tools / superpowers
§ 8

Frequently Asked Questions

frequently asked
§ 8.1
What is Worktrunk?
Worktrunk is a CLI for git worktree management, designed for running AI agents in parallel. Worktrees are addressed by branch name and paths are computed from a configurable template, which makes worktrees as easy as branches.
§ 8.2
How do I use it with Claude Code?
`wt switch -c -x claude feat` creates a worktree and starts Claude in it. Installing the plugin with `wt config plugins claude install` adds activity tracking (🤖/💬 in `wt list`) and routes Claude Code's worktree isolation through `wt switch --create` and `wt remove`.
§ 8.3
How do I install Worktrunk?
Run `brew install worktrunk && wt config shell install` on macOS and Linux, or `cargo install worktrunk && wt config shell install`. Shell integration allows commands to change directories.
§ 8.4
Does it work on Windows?
Yes, via Winget. `wt` defaults to Windows Terminal's command, so Winget additionally installs Worktrunk as `git-wt`. Alternatively, disable Windows Terminal's app execution alias to use `wt` directly.
§ 8.5
Which agent CLIs does it support besides Claude Code?
Worktrunk ships plugins for Codex, OpenCode, Pi, oh-my-pi, and Gemini CLI. Every plugin provides activity tracking, while the configuration skill, worktree isolation, and the `/wt-diff` pane depend on the hooks each CLI exposes.
§ 8.6
Is Worktrunk free?
Yes. It is open source, dual-licensed under MIT and Apache-2.0. LLM commit messages pipe a prompt to an external command such as Claude Code, so that tool's usage applies.