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

:

/.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: Check if LLM tool exists which llm

or: which aichat

If not installed, guide installation (don't run it) uv tool install -U llm Guide API key setup (don't run it) llm install llm-anthropic llm keys set anthropic llm models default claude-haiku-4.5 Propose config change [ commit-generation ] command = "llm" Ask: "Should I add this to your config?" After approval, apply Check if config exists: wt config show If not, guide through wt config create Read, modify, write preserving structure 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: Detect project type ls package.json Cargo.toml pyproject.toml Identify available commands For npm: Read package.json scripts For Rust: Common cargo commands For Python: Check pyproject.toml 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 Validate commands work npm run lint

verify exists

which cargo

verify tool exists

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" Add comments explaining choices 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: Read existing config : cat .config/wt.toml 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 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" 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 -x claude -- ''" Zellij (check $ZELLIJ env var): zellij run -- wt switch --create < branch-name

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