worktrunk

Product Introduction

1. Definition: Worktrunk is a command-line interface (CLI) tool designed for advanced Git worktree management. It is a developer productivity utility that sits atop Git's native git worktree functionality, specifically engineered to streamline parallel development workflows.
2. Core Value Proposition: Worktrunk exists to solve the clunky user experience of managing multiple Git worktrees, making them as simple to use as Git branches. Its primary value is enabling developers and AI agents to work on numerous features, fixes, or experiments in parallel without context-switching penalties or file conflicts, thereby accelerating development velocity and facilitating modern AI-assisted coding practices.

Main Features

1. Core Worktree Commands: Worktrunk provides simplified, intuitive commands for the entire worktree lifecycle. wt switch creates and switches to worktrees in one step, using configurable path templates. wt list displays a rich, color-coded status view showing branch relationships, commit states, and change summaries. wt merge orchestrates a complete local merge workflow (squash, rebase, fast-forward) and cleanup. wt remove safely deletes the worktree and its associated branch.
2. Workflow Automation via Hooks: The tool supports event-driven hooks (e.g., on_create, pre_merge) that execute shell scripts or commands. This allows for automated environment setup per worktree, such as installing dependencies, seeding databases, or starting dedicated development servers, which is critical for consistent parallel agent environments.
3. Advanced Integrations & Optimizations: Worktrunk includes an interactive picker with streaming CI status and diff previews. It features LLM-powered commit message generation by analyzing diffs. For performance, it leverages copy-on-write filesystem capabilities (APFS, btrfs, XFS) to share build caches (node_modules/, target/) across worktrees without duplication. It also integrates with GitHub/GitLab via wt switch pr:123 for direct PR checkout.

Problems Solved

1. Pain Point: The native Git worktree command-line interface is verbose and manual, requiring repetitive path and branch naming, which hinders rapid context switching and parallel task management, especially when scaling beyond 2-3 concurrent workstreams.
2. Target Audience: The primary users are software engineers, particularly those working on monorepos or complex features, and developers leveraging multiple AI coding agents (like Claude Code, Cursor, GitHub Copilot) in parallel. It also benefits open-source maintainers and DevOps engineers managing multiple patches or versions simultaneously.
3. Use Cases: Essential scenarios include: running 5-10+ AI agents on different tasks concurrently; conducting isolated performance experiments or security audits on a production codebase; managing simultaneous bug fixes and feature development; and providing ephemeral, fully-configured review environments for each pull request.

Unique Advantages

1. Strengths & Limitations (Pros & Cons):

   • Pros: Drastically reduces cognitive overhead and command friction for parallel development. The hook system and copy-on-write caches provide significant automation and performance gains. The rich wt list output and interactive picker offer superior visibility into multi-branch states. It is a single, fast binary with no runtime dependencies.
   • Cons: It is a CLI tool, requiring comfort with the terminal. Its full power is unlocked on supported copy-on-write filesystems (APFS, btrfs, XFS). Advanced configuration (hooks, templates) requires editing TOML files. It abstracts Git commands, so users must understand underlying git worktree concepts for troubleshooting.

2. Key Alternatives & Differentiation:

   • Native git worktree: The baseline alternative. Worktrunk differentiates by providing a vastly superior developer experience (DX) with shorter commands, intelligent defaults, path templates, and comprehensive status overviews, which the native tool lacks.
   • IDE/Editor Built-in Features: IDEs like VS Code or JetBrains IDEs have GUI-based branch management. Worktrunk differentiates by being editor-agnostic, scriptable, optimized for headless/agent-based workflows, and offering deeper system-level integrations like shared caches and hooks.
   • Custom Shell Scripts/Wrappers: Many teams build their own scripts. Worktrunk is a mature, feature-complete, and maintained alternative that offers a consistent, well-documented interface with built-in features like LLM commits and CI integration, avoiding the maintenance burden of custom scripts.

Frequently Asked Questions (FAQ)

1. How does Worktrunk handle merge conflicts during wt merge? Worktrunk's wt merge command orchestrates the merge process but delegates the actual Git operations. If a rebase or merge conflict occurs, the process pauses, and the user must resolve the conflicts manually using standard Git commands within the worktree before continuing the workflow.
2. Can Worktrunk be used with any Git hosting service like GitHub or GitLab? Yes, Worktrunk is agnostic to the Git remote host. Its features like wt list --full (CI status) and wt switch pr:123 rely on the gh (GitHub CLI) or glab (GitLab CLI) tools being installed and authenticated to fetch pull/merge request data.
3. Is Worktrunk safe to use on my main repository? Worktrunk is designed to be non-destructive and uses standard Git commands under the hood. However, as with any Git tool, it is recommended to understand the commands (e.g., wt remove deletes the branch) and ensure your work is committed or stashed. Using it on a backup clone first is a good practice.
4. What are the system requirements for the copy-on-write build cache feature? The shared build cache feature requires your project directory to be on a filesystem that supports reflinks (copy-on-write), specifically APFS on macOS, or btrfs/XFS on Linux. It will not work on traditional filesystems like ext4 or NTFS, though all other Worktrunk features will function normally.
5. How do I automate setting up a new worktree (e.g., run npm install)? You automate setup using Worktrunk's hook system. Define an on_create hook in ~/.config/worktrunk/config.toml that runs commands like npm install or cp .env.example .env. This hook executes automatically every time a new worktree is created with wt switch -c.