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 commit message generation", "configuring hooks", "automating tasks", or general worktrunk questions.
Help users work with Worktrunk, a CLI tool for managing git worktrees.
Reference files are synced from worktrunk.dev documentation:
For command-specific options, run wt <command> --help. For configuration, follow the workflows below.
Worktrunk uses two separate config files with different scopes and behaviors:
~/.config/worktrunk/config.toml)~/.config/worktrunk/config.toml (never checked into git)reference/config.md for detailed guidance.config/wt.toml)<repo>/.config/wt.toml (checked into git)reference/hook.md for detailed guidanceWhen a user asks for configuration help, determine which type based on:
User config indicators:
Project config indicators:
Both configs may be needed: For example, setting up commit message generation requires user config, but automating quality checks requires project 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
wt config showwt config createSuggest testing
wt step commit --show-prompt | head # verify prompt builds
wt merge # in a repo with uncommitted changes
Common request for workflow automation. Follow discovery process:
Detect project type
ls package.json Cargo.toml pyproject.toml
Identify available commands
package.json scriptsDesign appropriate hooks (7 hook types available)
post-createpre-commit or pre-mergepost-startpost-switchpost-mergepre-removeValidate 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.
When users want to add automation to an existing project:
Read existing config: cat .config/wt.toml
Determine hook type - When should this run?
post-createpost-startpost-switchpre-commitpre-mergepost-mergepre-removeHandle 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
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:
rm -rf, DROP TABLEcurl http://...sudoreference/llm-commits.mdreference/config.md#worktree-path-templatereference/llm-commits.md#templatesreference/config.md#command-settingsreference/config.md#user-hooksreference/hook.mdreference/hook.md#configurationreference/hook.md#template-variablesreference/config.md#dev-server-url# View all configuration
wt config show
# Create initial user config
wt config create
# LLM setup guide
wt config --help
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
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):
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.'