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 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 reference/llm-commits.md for supported tools and exact command syntax.

Detect available tools

which claude codex llm aichat 2>/dev/null

If none installed, recommend Claude Code (already available in Claude Code sessions)
Propose config change — Get the exact command from reference/llm-commits.md
```
[commit.generation]
command = "..."  # see reference/llm-commits.md for tool-specific commands
```
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

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:

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 commit message generation → 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.'

worktrunk