Worktrunk

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

Available Documentation

• SKILL.md: Configuration workflows and common patterns
• reference/user-config.md: User config (LLM, worktree paths, command defaults)
• reference/project-config.md: Project config (lifecycle hooks)
• reference/hook-types-reference.md: Detailed hook behavior and timing
• reference/shell-integration.md: Shell integration debugging

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/user-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/project-config.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/user-config.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/project-config.md for complete details.

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

Project Config Tasks

• Set up hooks for new project → reference/project-config.md#new-project
• Add hook to existing config → reference/project-config.md#add-hook
• Use template variables → reference/project-config.md#variables
• Convert command formats → reference/project-config.md#formats
• Add dev server URL to list → reference/project-config.md#dev-server-url
• Troubleshoot hook execution → reference/project-config.md#troubleshooting

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 "## LLM Setup" reference/user-config.md
grep -A 30 "### post-create" reference/project-config.md
grep -A 20 "## Warning Messages" reference/shell-integration.md