{"skill":{"slug":"worktrunk","displayName":"Worktrunk","summary":"Git worktree manager for parallel AI agent workflows. Use when the user needs to manage multiple working directories for parallel development, create feature...","description":"---\nname: worktrunk\ndescription: \"Git worktree manager for parallel AI agent workflows. Use when the user needs to manage multiple working directories for parallel development, create feature branches with isolated environments, or run multiple AI agents concurrently. Covers `vx worktrunk` and `vx wt` commands.\"\n---\n\n# Worktrunk — Git Worktree Manager for AI Agents\n\n> **One-sentence summary**: `vx worktrunk` (alias `vx wt`) manages Git worktrees so you can run multiple AI agents in parallel without conflicts.\n\nworktrunk 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.\n\n## Why AI Agents Need This\n\nWhen running multiple AI agents (Claude Code, Codex, etc.) on the same repo, they conflict:\n- Agent A modifies `src/main.rs`\n- Agent B modifies `src/main.rs` → **conflict**\n\n**Solution**: Give each agent its own worktree (isolated working directory).\n\n```\nMain repo:     ~/projects/my-app/          (main branch)\nAgent 1:      ~/projects/my-app.wt/feat-auth/  (feat/auth branch)\nAgent 2:      ~/projects/my-app.wt/feat-pay/   (feat/pay branch)\n```\n\n## Installation (via vx)\n\n```bash\nvx install worktrunk\nvx worktrunk --version    # verify\n```\n\n## Core Commands\n\n### `wt switch` — Navigate Worktrees\n\n```bash\n# Create new worktree + switch to it\nvx wt switch -c feat/auth\n\n# Switch to existing worktree\nvx wt switch feat/auth\n\n# Switch back to main repo\nvx wt switch -\n\n# Create AND launch an AI agent in one command\nvx wt switch -c -x claude feat/auth\n```\n\n### `wt list` — Show All Worktrees\n\n```bash\nvx wt list            # compact list\nvx wt list --full     # with CI status, AI-generated summaries, diff preview\n```\n\n### `wt merge` — Clean Merge Workflow\n\n```bash\nvx wt merge          # squash merge + delete worktree + delete branch\nvx wt merge --rebase  # rebase merge\nvx wt merge --keep    # merge but keep worktree\n```\n\n### `wt remove` — Clean Up\n\n```bash\nvx wt remove feat/auth          # remove worktree only\nvx wt remove --with-branch feat/auth  # remove worktree + branch\n```\n\n## Advanced Features\n\n### PR Checkout\n\n```bash\nvx wt switch pr:123    # checkout PR #123 into a worktree\n```\n\n### Hooks (Automate Setup)\n\nConfigure in `.worktrunk/hooks.toml`:\n\n```toml\n[post_create]\ncommand = \"npm install\"     # auto-install deps on create\n\n[pre_merge]\ncommand = \"vx run test\"      # run tests before merge\n```\n\n### Share Build Caches Between Worktrees\n\n```bash\n# Copy node_modules/ to new worktree (skip cold install)\nvx wt switch -c --copy-cache feat/auth\n```\n\n### Per-Worktree Dev Server (Unique Port)\n\nworktrunk can assign each worktree a unique port (via `hash_port` template filter):\n\n```bash\n# In package.json:\n\"scripts\": {\n  \"dev\": \"next dev -p {{ hash_port 3000 }}\"\n}\n# Main repo  → port 3000\n# feat/auth → port 3217 (deterministic hash)\n```\n\n## Typical AI Agent Workflow\n\n```bash\n# 1. Main repo: assign tasks to agents\ncd ~/projects/my-app\necho \"Add JWT auth\" > .AITASK\n\n# 2. Create isolated worktree for agent 1\nvx wt switch -c -x claude feat/auth\n\n# (inside worktree, agent runs autonomously)\n# Agent modifies files, commits, etc.\n\n# 3. Meanwhile, create another worktree for agent 2\nvx wt switch -c -x claude feat/pay\n\n# 4. When agents finish, merge both\nvx wt merge feat/auth\nvx wt merge feat/pay\n```\n\n## vx Integration\n\nworktrunk is installed and managed by vx:\n\n```bash\n# Install\nvx install worktrunk\n\n# Run (vx auto-installs if missing)\nvx worktrunk --version\nvx wt switch -c feat/auth\n\n# Update\nvx install worktrunk@latest\n```\n\n## Command Reference\n\n| Command | Description |\n|----------|-------------|\n| `vx wt switch [branch]` | Switch to worktree |\n| `vx wt switch -c [branch]` | Create worktree + switch |\n| `vx wt switch -c -x <cmd> [branch]` | Create + run command (e.g., launch AI agent) |\n| `vx wt switch pr:<number>` | Checkout PR into worktree |\n| `vx wt list` | List worktrees |\n| `vx wt list --full` | Detailed list with CI/LLM summary |\n| `vx wt merge` | Squash merge + cleanup |\n| `vx wt remove [branch]` | Remove worktree |\n| `vx wt remove --with-branch [branch]` | Remove worktree + branch |\n\n## Tips for AI Agents\n\n1. **Always use `vx wt switch -c`** to create isolated environments before making changes\n2. **Use `-x claude`** to automatically launch the AI agent in the new worktree\n3. **Use `vx wt merge`** instead of manual `git merge` — it handles worktree cleanup\n4. **Configure hooks** in `.worktrunk/hooks.toml` to auto-install dependencies on create\n5. **Use `--copy-cache`** to share `node_modules/` / `target/` between worktrees\n","topics":["Git"],"tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":339,"installsAllTime":13,"installsCurrent":1,"stars":0,"versions":1},"createdAt":1777701764572,"updatedAt":1778492826217},"latestVersion":{"version":"1.0.0","createdAt":1777701764572,"changelog":"Initial release of worktrunk: a Git worktree manager optimized for parallel AI agent workflows.\n\n- Introduces `vx worktrunk` (`vx wt`) CLI commands to create, switch, and manage Git worktrees easily.\n- Designed to eliminate file conflicts by giving each AI agent its own isolated working directory.\n- Adds features like per-worktree dev servers, hooks for automating setup/merge, and cache sharing.\n- Supports workflows for managing feature branches, checking out PRs, and merging/cleaning up worktrees efficiently.\n- Full vx integration for installation, updates, and command execution.","license":"MIT-0"},"metadata":null,"owner":{"handle":"loonghao","userId":"s176cy7je3jzfnkewtyz7ja0e183m3t9","displayName":"Hal","image":"https://avatars.githubusercontent.com/u/13111745?v=4"},"moderation":null}