Worktrunk — Git Worktree Manager for AI Agents

One-sentence summary: vx worktrunk (alias vx wt) manages Git worktrees so you can run multiple AI agents in parallel without conflicts.

worktrunk is a Rust CLI tool designed for parallel AI agent workflows. It makes Git worktrees as easy to use as branches, with quality-of-life features like hooks, LLM commit messages, and per-worktree dev servers.

Why AI Agents Need This

When running multiple AI agents (Claude Code, Codex, etc.) on the same repo, they conflict:

• Agent A modifies src/main.rs
• Agent B modifies src/main.rs → conflict

Solution: Give each agent its own worktree (isolated working directory).

Main repo:     ~/projects/my-app/          (main branch)
Agent 1:      ~/projects/my-app.wt/feat-auth/  (feat/auth branch)
Agent 2:      ~/projects/my-app.wt/feat-pay/   (feat/pay branch)

Installation (via vx)

vx install worktrunk
vx worktrunk --version    # verify

Core Commands

wt switch — Navigate Worktrees

# Create new worktree + switch to it
vx wt switch -c feat/auth

# Switch to existing worktree
vx wt switch feat/auth

# Switch back to main repo
vx wt switch -

# Create AND launch an AI agent in one command
vx wt switch -c -x claude feat/auth

wt list — Show All Worktrees

vx wt list            # compact list
vx wt list --full     # with CI status, AI-generated summaries, diff preview

wt merge — Clean Merge Workflow

vx wt merge          # squash merge + delete worktree + delete branch
vx wt merge --rebase  # rebase merge
vx wt merge --keep    # merge but keep worktree

wt remove — Clean Up

vx wt remove feat/auth          # remove worktree only
vx wt remove --with-branch feat/auth  # remove worktree + branch

Advanced Features

PR Checkout

vx wt switch pr:123    # checkout PR #123 into a worktree

Hooks (Automate Setup)

Configure in .worktrunk/hooks.toml:

[post_create]
command = "npm install"     # auto-install deps on create

[pre_merge]
command = "vx run test"      # run tests before merge

Share Build Caches Between Worktrees

# Copy node_modules/ to new worktree (skip cold install)
vx wt switch -c --copy-cache feat/auth

Per-Worktree Dev Server (Unique Port)

worktrunk can assign each worktree a unique port (via hash_port template filter):

# In package.json:
"scripts": {
  "dev": "next dev -p {{ hash_port 3000 }}"
}
# Main repo  → port 3000
# feat/auth → port 3217 (deterministic hash)

Typical AI Agent Workflow

# 1. Main repo: assign tasks to agents
cd ~/projects/my-app
echo "Add JWT auth" > .AITASK

# 2. Create isolated worktree for agent 1
vx wt switch -c -x claude feat/auth

# (inside worktree, agent runs autonomously)
# Agent modifies files, commits, etc.

# 3. Meanwhile, create another worktree for agent 2
vx wt switch -c -x claude feat/pay

# 4. When agents finish, merge both
vx wt merge feat/auth
vx wt merge feat/pay

vx Integration

worktrunk is installed and managed by vx:

# Install
vx install worktrunk

# Run (vx auto-installs if missing)
vx worktrunk --version
vx wt switch -c feat/auth

# Update
vx install worktrunk@latest

Command Reference

Tips for AI Agents

1. Always use vx wt switch -c to create isolated environments before making changes
2. Use -x claude to automatically launch the AI agent in the new worktree
3. Use vx wt merge instead of manual git merge — it handles worktree cleanup
4. Configure hooks in .worktrunk/hooks.toml to auto-install dependencies on create
5. Use --copy-cache to share node_modules/ / target/ between worktrees

Delivery Surface — External Systems Are Evidence

GitHub PRs, CI runs, and dashboards are supporting evidence, not the delivery surface. The conclusion has to land where the work is tracked.

• Record the outcome once, completely — one issue comment carrying status, branch/commit/PR, what you validated, the blocker, and the next owner.
• Verify terminal state, not intermediate state. A green CI run or an open, review-ready PR is not "shipped". Confirm merged / released / deployed, then record that.
• Keep public surfaces public-safe. PR titles, bodies, and commit messages carry technical content only — no internal issue IDs, routing history, reviewer handoffs, local absolute paths, or internal hostnames.
• Collect results in the foreground. A queued or pending state is a handoff, not a completion; never end a turn "standing by" for background work.

Concretely: the delivery surface is the team's issue or task tracker — the issue comment plus its metadata. A PR comment alone delivers nothing.