Worktrunk

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

Available Documentation

Reference files are synced from worktrunk.dev documentation:

• reference/config.md: User and project configuration (LLM, hooks, command defaults)
• reference/hook.md: Hook types, timing, and execution order
• reference/switch.md, merge.md, list.md, etc.: Command documentation
• reference/llm-commits.md: LLM commit message generation
• reference/tips-patterns.md: Language-specific tips and patterns
• reference/shell-integration.md: Shell integration debugging
• reference/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: reference/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 (post-create, pre-merge, etc.)
• Permission model: Proactive (create directly, changes are reversible via git)
• See: reference/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 LLM integration requires user config, but automating quality checks requires project config.

Core Workflows

Setting Up LLM Integration (User Config)

Most common request. Follow this sequence:

1. Check if LLM tool exists

   which llm  # or: which aichat
   

2. If not installed, guide installation (don't run it)

   uv tool install -U llm
   

3. Guide API key setup (don't run it)

   llm install llm-anthropic
   llm keys set anthropic
   llm models default claude-haiku-4.5
   

4. Propose config change

   [commit-generation]
   command = "llm"
   

   Ask: "Should I add this to your config?"

5. After approval, apply

   • Check if config exists: wt config show
   • If not, guide through wt config create
   • Read, modify, write preserving structure

6. Suggest testing

   llm "say hello"
   wt merge  # in a repo with uncommitted changes
   

See reference/config.md and reference/llm-commits.md for complete details.

Setting Up Project Hooks (Project Config)

Common request for workflow automation. Follow discovery process:

1. Detect project type

   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 (7 hook types available)

   • Dependencies (fast, must complete) → post-create
   • Tests/linting (must pass) → pre-commit or pre-merge
   • Long builds, dev servers → post-start
   • Terminal/IDE updates → post-switch
   • Deployment → post-merge
   • Cleanup tasks → pre-remove

4. Validate commands work

   npm run lint  # verify exists
   which cargo   # verify tool exists
   

5. Create .config/wt.toml

   # Install dependencies when creating worktrees
   post-create = "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

   wt switch --create test-hooks
   

See reference/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) → post-create
   • Creating worktree (background) → post-start
   • Every switch → post-switch
   • Before committing → pre-commit
   • Before merging → pre-merge
   • After merging → post-merge
   • Before removal → pre-remove

3. Handle format conversion if needed

   Single command to named table:

   # Before
   post-create = "npm install"
   
   # After (adding db:migrate)
   [post-create]
   install = "npm install"
   migrate = "npm run db:migrate"
   

4. Preserve existing structure and comments

Validation Before Adding Commands

Before adding hooks, validate:

# 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 LLM integration → reference/llm-commits.md
• Customize worktree paths → reference/config.md#worktree-path-template
• Custom commit templates → reference/llm-commits.md#templates
• Configure command defaults → reference/config.md#command-settings
• Set up personal hooks → reference/config.md#user-hooks

Project Config Tasks

• Set up hooks for new project → reference/hook.md
• Add hook to existing config → reference/hook.md#configuration
• Use template variables → reference/hook.md#template-variables
• Add dev server URL to list → reference/config.md#dev-server-url

Key Commands

# 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:

grep -A 20 "## Setup" reference/llm-commits.md
grep -A 30 "### post-create" reference/hook.md
grep -A 20 "## Warning Messages" reference/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):

tmux new-session -d -s <branch-name> "wt switch --create <branch-name> -x claude -- '<task description>'"

Zellij (check $ZELLIJ env var):

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):

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):

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.'