wt: A Git Worktree Orchestrator for Parallel AI Agent Development

Concurrent AI agent development introduces coordination problems when multiple agents modify the same repository. File conflicts occur when agents operate on overlapping code paths, and resolving these conflicts consumes agent context that would otherwise be applied to the task.

Git worktrees provide filesystem isolation while sharing repository state—each worktree maintains an independent working directory and branch reference without duplicating the object database. However, the native git worktree interface requires verbose commands, manual cleanup, and lacks primitives for managing multiple concurrent sessions.

wt is a CLI tool that addresses these limitations.

Overview

wt wraps git worktree operations in an interface designed for multi-agent workflows:

# Create an isolated workspace
wt new feature/auth

# Spawns a subshell with modified working directory and branch
# Shell prompt reflects workspace context
(wt:feature/auth) $ claude

# On completion, exit subshell and merge
exit
git merge feature/auth

Workspaces provide complete filesystem isolation. Each agent operates on an independent working directory, and changes integrate via standard git merge or rebase operations.

Workspace Management

wt provides both interactive and direct workspace access:

wt ls                  # Interactive picker (TUI) for workspace selection
wt use feature/auth    # Enter a specific workspace directly
wt which               # Display current workspace context
wt rm feature/auth     # Remove worktree and optionally delete branch

Tmux Session Management

wt integrates with tmux to coordinate multiple concurrent agent processes:

wt session new my-sprint
wt session add feature/auth
wt session add bugfix/header
wt session add feature/payments

Each workspace maps to a tmux window with a configurable pane layout: 2-pane (agent CLI + terminal) or 3-pane (agent + terminal + editor).

The wt session watch command displays agent activity state by monitoring pane output:

● feature/auth      (running)
○ bugfix/header     (idle)
● feature/payments  (running)

Activity detection uses output buffer analysis to distinguish active processing from prompt-waiting states.

Claude Code Integration

wt includes a /do skill for Claude Code that implements issue-driven workflows:

/do gh 123          # GitHub issue #123
/do sc 45678        # Shortcut story 45678

The skill executes the following operations:

1. Fetch issue/story metadata from the respective API
2. Create a worktree with a branch name derived from the issue identifier
3. Populate agent context with issue description and acceptance criteria
4. On task completion, create a commit with the issue reference in the message

Configuration

Configuration follows a precedence chain: CLI flags → repo-local .wt.toml → global ~/.wt/config.toml → defaults.

# .wt.toml (repository root)
panes = 3
agent_cmd = "claude"
editor_cmd = "nvim"

Files listed under a # wt copy marker in .gitignore are symlinked from the main worktree into each spawned worktree:

# wt copy
.env
.env.local
credentials.json

This mechanism handles environment files and credentials that are gitignored but required at runtime.

Implementation

wt is implemented in Rust. The crate structure:

• WorktreeManager: Wraps `git worktree` subcommands, maintains branch-to-directory mappings, handles cleanup of stale worktrees
• TmuxManager: Interfaces with tmux via `tmux` CLI commands, monitors pane output buffers for activity detection
• ShellEnvironment: Spawns subshells (bash, zsh, fish) with modified `$PWD` and environment variables reflecting workspace state
• SessionState: Persists session metadata to JSON, reconciles with actual tmux state on load

Branch names containing forward slashes require path sanitization. Git permits feature/auth as a branch name, but using this directly as a directory path would create nested directories. wt normalizes slashes to double-dashes in directory names (feature--auth) while preserving the git ref name.

Installation

Pre-compiled binaries are available for macOS and Linux (x86_64, aarch64). Building from source:

git clone https://github.com/pld/wt
cd wt
cargo build --release

The binary includes an install subcommand that configures shell aliases and installs the Claude Code skill definition.

Discussion

Single-agent workflows operate adequately with standard git branching. Multi-agent parallelism introduces coordination overhead that scales with agent count: conflict resolution, context switching between agent sessions, and manual worktree lifecycle management.

wt reduces this overhead by mapping each agent to an isolated worktree and providing primitives for session orchestration. The tradeoff is an additional abstraction layer over git; the benefit is that agents operate independently until explicit merge points.

Source: github.com/pld/wt