# Worktrunk

> Expert guide for Worktrunk (the `wt` CLI), a git worktree manager designed for running AI agents in parallel. Invoke this skill whenever a user mentions worktrunk or wt commands (wt switch, wt list, wt merge, wt remove, wt hook, wt step, wt config), asks about git worktrees for AI agents or parallel development, wants to configure LLM commit messages, set up worktree lifecycle hooks, run multiple Claude or Codex agents simultaneously, use wt list CI status, configure the interactive picker, copy build caches between worktrees, or troubleshoot shell integration. Also use for questions about .config/wt.toml, ~/.config/worktrunk/config.toml, hash_port, sanitize filters, wt merge squash/rebase workflow, wt step copy-ignored, wt step prune, agent handoffs, dev servers per worktree, bare repository layouts, or any other worktrunk topic.

- Skill: `kpatryk/worktrunk` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add kpatryk/worktrunk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kpatryk/worktrunk/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: kpatryk (https://skillmd.com/u/kpatryk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kpatryk/worktrunk

---


# Worktrunk

Help users work with Worktrunk, a CLI tool for managing git worktrees.

## Available Documentation

Reference files are synced from [worktrunk.dev](https://worktrunk.dev) documentation:

- **references/config.md**: User and project configuration (LLM, hooks, command defaults)
- **references/hook.md**: Hook types, timing, and execution order
- **references/switch.md**, **merge.md**, **list.md**, etc.: Command documentation
- **references/llm-commits.md**: LLM commit message generation
- **references/tips-patterns.md**: Language-specific tips and patterns
- **references/shell-integration.md**: Shell integration debugging
- **references/troubleshooting.md**: Troubleshooting for LLM and hooks (Claude-specific)

For command-specific options, run `wt <command> --help`. For configuration, follow the workflows below.

## Two Types of Configuration

Worktrunk uses two separate config files with different scopes and behaviors:

### User Config (`~/.config/worktrunk/config.toml`)
- **Scope**: Personal preferences for the individual developer
- **Location**: `~/.config/worktrunk/config.toml` (never checked into git)
- **Contains**: LLM integration, worktree path templates, command settings, user hooks, approved commands
- **Permission model**: Always propose changes and get consent before editing
- **See**: `references/config.md` for detailed guidance

### Project Config (`.config/wt.toml`)
- **Scope**: Team-wide automation shared by all developers
- **Location**: `<repo>/.config/wt.toml` (checked into git)
- **Contains**: Hooks for worktree lifecycle (pre-start, post-start, pre-merge, etc.)
- **Permission model**: Proactive (create directly, changes are reversible via git)
- **See**: `references/hook.md` for detailed guidance

## Determining Which Config to Use

When a user asks for configuration help, determine which type based on:

**User config indicators**:
- "set up LLM" or "configure commit generation"
- "change where worktrees are created"
- "customize commit message templates"
- Affects only their environment

**Project config indicators**:
- "set up hooks for this project"
- "automate npm install"
- "run tests before merge"
- Affects the entire team

**Both configs may be needed**: For example, setting up commit message generation requires user config, but automating quality checks requires project config.

## Core Workflows

### Setting Up Commit Message Generation (User Config)

Most common request. See `references/llm-commits.md` for supported tools and exact command syntax.

1. **Detect available tools**
   ```bash
   which claude codex llm aichat 2>/dev/null
   ```

2. **If none installed, recommend Claude Code** (already available in Claude Code sessions)

3. **Propose config change** — Get the exact command from `references/llm-commits.md`
   ```toml
   [commit.generation]
   command = "..."  # see references/llm-commits.md for tool-specific commands
   ```
   Ask: "Should I add this to your config?"

4. **After approval, apply**
   - Check if config exists: `wt config show`
   - If not, guide through `wt config create`
   - Read, modify, write preserving structure

5. **Suggest testing**
   ```bash
   wt step commit --show-prompt | head  # verify prompt builds
   wt merge  # in a repo with uncommitted changes
   ```

### Setting Up Project Hooks (Project Config)

Common request for workflow automation. Follow discovery process:

1. **Detect project type**
   ```bash
   ls package.json Cargo.toml pyproject.toml
   ```

2. **Identify available commands**
   - For npm: Read `package.json` scripts
   - For Rust: Common cargo commands
   - For Python: Check pyproject.toml

3. **Design appropriate hooks** (10 hook types across 5 lifecycle events)
   - Dependencies that must finish before work starts → `pre-start` (blocks)
   - Long builds, dev servers, file watchers → `post-start` (background)
   - Tests/linting (must pass before commit) → `pre-commit`
   - Quality gates (must pass before merge) → `pre-merge`
   - Terminal/IDE updates on every switch → `post-switch`
   - Deployment, notifications → `post-merge`
   - Save artifacts before deletion → `pre-remove`
   - Stop servers, remove containers → `post-remove`

4. **Validate commands work**
   ```bash
   npm run lint  # verify exists
   which cargo   # verify tool exists
   ```

5. **Create `.config/wt.toml`**
   ```toml
   # Install dependencies when creating worktrees (blocks until done)
   pre-start = "npm install"

   # Validate code quality before committing
   [pre-commit]
   lint = "npm run lint"
   typecheck = "npm run typecheck"

   # Run tests before merging
   pre-merge = "npm test"
   ```

6. **Add comments explaining choices**

7. **Suggest testing**
   ```bash
   wt switch --create test-hooks
   ```

**See `references/hook.md` for complete details.**

### Adding Hooks to Existing Config

When users want to add automation to an existing project:

1. **Read existing config**: `cat .config/wt.toml`

2. **Determine hook type** - When should this run?
   - Creating worktree (blocking, must finish first) → `pre-start`
   - Creating worktree (background, fire-and-forget) → `post-start`
   - Every switch (blocking) → `pre-switch`; (background) → `post-switch`
   - Before committing → `pre-commit`
   - Before merging → `pre-merge`
   - After merging → `post-merge`
   - Before removal → `pre-remove`
   - After removal → `post-remove`

3. **Handle format conversion if needed**

   Single command to named table:
   ```toml
   # Before
   pre-start = "npm install"

   # After (adding db:migrate)
   [pre-start]
   install = "npm install"
   migrate = "npm run db:migrate"
   ```

4. **Preserve existing structure and comments**

### Validation Before Adding Commands

Before adding hooks, validate:

```bash
# Verify command exists
which npm
which cargo

# For npm, verify script exists
npm run lint --dry-run

# For shell commands, check syntax
bash -n -c "if [ true ]; then echo ok; fi"
```

**Dangerous patterns** — Warn users before creating hooks with:
- Destructive commands: `rm -rf`, `DROP TABLE`
- External dependencies: `curl http://...`
- Privilege escalation: `sudo`

## Permission Models

### User Config: Conservative
- **Never edit without consent** - Always show proposed change and wait for approval
- **Never install tools** - Provide commands for users to run themselves
- **Preserve structure** - Keep existing comments and organization
- **Validate first** - Ensure TOML is valid before writing

### Project Config: Proactive
- **Create directly** - Changes are versioned, easily reversible
- **Validate commands** - Check commands exist before adding
- **Explain choices** - Add comments documenting why hooks exist
- **Warn on danger** - Flag destructive operations before adding

## Common Tasks Reference

### User Config Tasks
- Set up commit message generation → `references/llm-commits.md`
- Customize worktree paths → `references/config.md#worktree-path-template`
- Custom commit templates → `references/llm-commits.md#templates`
- Configure command defaults → `references/config.md#command-settings`
- Set up personal hooks → `references/config.md#user-hooks`

### Project Config Tasks
- Set up hooks for new project → `references/hook.md`
- Add hook to existing config → `references/hook.md#configuration`
- Use template variables → `references/hook.md#template-variables`
- Add dev server URL to list → `references/config.md#dev-server-url`

## Key Commands

```bash
# View all configuration
wt config show

# Create initial user config
wt config create

# LLM setup guide
wt config --help
```

## Loading Additional Documentation

Load **reference files** for detailed configuration, hook specifications, and troubleshooting.

Find specific sections with grep:
```bash
grep -A 20 "## Setup" references/llm-commits.md
grep -A 30 "## pre-start" references/hook.md
grep -A 20 "## Warning Messages" references/shell-integration.md
```

## Advanced: Agent Handoffs

When the user requests spawning a worktree with Claude in a background session ("spawn a worktree for...", "hand off to another agent"), use the appropriate pattern for their terminal multiplexer:

**tmux** (check `$TMUX` env var):
```bash
tmux new-session -d -s <branch-name> "wt switch --create <branch-name> -x claude -- '<task description>'"
```

**Zellij** (check `$ZELLIJ` env var):
```bash
zellij run -- wt switch --create <branch-name> -x claude -- '<task description>'
```

**Requirements** (all must be true):
- User explicitly requests spawning/handoff
- User is in a supported multiplexer (tmux or Zellij)
- User's CLAUDE.md or explicit instruction authorizes this pattern

**Do not use this pattern** for normal worktree operations.

Example (tmux):
```bash
tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \
  'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'"
```

Example (Zellij):
```bash
zellij run -- wt switch --create fix-auth-bug -x claude -- \
  'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'
```