Agent Skills: Worktrunk Skill

Worktrunk Skill

Worktrunk (wt) is a CLI for git worktree management designed to run AI agents (like Claude Code) in parallel across isolated branches. Think of it as making git worktree as easy as git branch.

Quick Reference

| Task | Command | | ------------------------------- | ----------------------------------- | | Create worktree + switch | wt switch --create feat | | Create worktree + launch Claude | wt switch --create feat -x claude | | List all worktrees | wt list | | Merge & clean up | wt merge main | | Remove current worktree | wt remove | | Commit staged changes | wt step commit |

Installation

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

# Cargo
cargo install worktrunk && wt config shell install

# Windows
winget install max-sixty.worktrunk
git-wt config shell install

Shell integration (wt config shell install) is required so that wt switch can actually change the shell's directory.

Core Workflow

1. Create and Switch

wt switch --create feature-auth         # New branch + worktree
wt switch --create feature-auth -x claude  # + launch Claude in it
wt switch existing-branch               # Switch to existing worktree
wt switch -                             # Previous worktree

Worktrees are placed at ../repo.branch-name by default (configurable).

2. Inspect Status

wt list                    # All worktrees with status, commits, CI
wt list --full --branches  # Include remote branches without worktrees
wt list --format=json      # Machine-readable output

Key indicators in wt list:

• @ = current worktree
• + / - = staged / unstaged changes
• ↑ / ↓ = ahead / behind remote
• ⇡ / ⇣ = ahead / behind default branch
• 🤖 = Claude is working (Claude Code plugin)
• 💬 = Claude waiting for input

3. Parallel Agents Pattern

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'

-x / --execute runs a command after switching; arguments after -- are passed to it.

4. Merge or Clean Up

PR workflow:

wt step commit              # Commit staged changes with optional LLM message
gh pr create                # Open PR
wt remove                   # After PR merged

Local merge (squash + rebase + fast-forward):

wt merge main
# Commits, rebases onto main, fast-forward merges, removes worktree

Hooks

Hooks automate worktree lifecycle events. Define in .config/wt.toml (project) or ~/.config/worktrunk/config.toml (user/global).

See references/hooks.md for the full hook reference, template variables, and common patterns (dev servers, databases, cold-start elimination).

Hook Types at a Glance

| Hook | When | Blocking | | ------------- | ------------------- | ---------------------- | | post-create | After creation | Yes (blocks --execute) | | post-start | After creation | No (background) | | post-switch | Every switch | No | | pre-commit | Before merge commit | Yes | | pre-merge | Before merge | Yes | | post-merge | After merge | Yes | | pre-remove | Before removal | Yes | | post-remove | After removal | No |

Essential Hook Patterns

Eliminate cold starts (copy deps/caches/env from main):

[post-start]
copy = "wt step copy-ignored"

Dev server per worktree (deterministic port from branch name):

[post-start]
server = "npm run dev -- --port {{ branch | hash_port }}"
[pre-remove]
server = "lsof -ti :{{ branch | hash_port }} -sTCP:LISTEN | xargs kill 2>/dev/null || true"

Local CI gate (run tests before merge):

[pre-merge]
test = "npm test"
build = "npm run build"

Template Variables & Filters

In hook commands (Jinja2 syntax):

| Variable | Value | | ---------------------- | -------------------------------- | | {{ branch }} | Branch name | | {{ repo }} | Repository directory name | | {{ worktree_path }} | Absolute path to this worktree | | {{ default_branch }} | Default branch name | | {{ target }} | Target branch (merge hooks only) |

| Filter | Example | Output | | ------------- | ----------------------------- | ----------------------- | | sanitize | {{ branch \| sanitize }} | / and \ → - | | sanitize_db | {{ branch \| sanitize_db }} | DB-safe identifier | | hash_port | {{ branch \| hash_port }} | Stable port 10000-19999 |

LLM Commit Messages

Generate commit messages from diffs:

wt step commit              # Commit staged changes, generate message
wt step commit --all        # Stage all + commit

Configure in ~/.config/worktrunk/config.toml:

[commit.generation]
model = "claude-opus-4-5"   # or any supported model
provider = "anthropic"

Claude Code Integration

Install the plugin for activity tracking (🤖 / 💬 in wt list) and configuration skill:

claude plugin marketplace add max-sixty/worktrunk
claude plugin install worktrunk@worktrunk

Add to ~/.claude/settings.json for statusline:

{
  "statusLine": {
    "type": "command",
    "command": "wt list statusline --format=claude-code"
  }
}

Zellij Integration

Spawn agent handoffs directly into Zellij panes (great with your existing Zellij setup):

zellij run -- wt switch --create fix-auth -x claude -- \
  'Fix the session timeout bug in auth module'

Or use hooks for a full multi-pane layout per worktree:

# .config/wt.toml
[post-create]
zellij = """
zellij action new-tab --name {{ branch | sanitize }}
zellij action new-pane -- claude
"""

Common Commands for devops Work

For microservice's repos, a typical .config/wt.toml:

[post-create]
env = "cp {{ primary_worktree_path }}/.env.local .env.local 2>/dev/null || true"

[post-start]
copy = "wt step copy-ignored"

[pre-merge]
lint = "make lint"
test = "make test"

[post-merge]
notify = "echo '✓ Merged {{ branch }} → {{ target }}'"

Further Reference

• references/hooks.md — Complete hook documentation with all patterns
• references/commands.md — Full command reference (switch, list, merge, remove, step, config)
• Official docs: https://worktrunk.dev
• Claude Code integration: https://worktrunk.dev/claude-code/
• Tips & patterns: https://worktrunk.dev/tips-patterns/