worktrunk

name	worktrunk
description	Guidance for Worktrunk, a CLI tool for managing git worktrees. Covers configuration (user config at ~/.config/worktrunk/config.toml and project hooks at .config/wt.toml), usage, and troubleshooting. Use for "setting up LLM", "configuring hooks", "automating tasks", or general worktrunk questions.

Worktrunk

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

Available Documentation

• SKILL.md: Configuration workflows and common patterns
• reference/README.md: Features, installation, examples, FAQ
• reference/*.md: Detailed configuration and hook specifications

For general usage, consult reference/README.md. 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, 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-20251001
   

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 list
   • 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

   • Dependencies (fast, must complete) → post-create
   • Tests/linting (must pass) → pre-commit or pre-merge
   • Long builds → post-start

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
• 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
• Troubleshoot hook execution → reference/project-config.md#troubleshooting

Key Commands

# View all configuration
wt config list

# Create initial user config
wt config create

# LLM setup guide
wt config --help

Loading Additional Documentation

Load reference/README.md for general features, installation, commands, and examples.

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

Find specific sections with grep:

grep -A 20 "## Installation" reference/README.md
grep -A 20 "## LLM Setup" reference/user-config.md
grep -A 30 "### post-create" reference/project-config.md