Worktrunk

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/extending.md: Aliases, multi-step pipelines, custom subcommands, and template-expansion gotchas (two-pass {% raw %} deferral, for-each recipes)
• reference/llm-commits.md: LLM commit message generation
• reference/tips-patterns.md: Practical recipes — aliases, per-branch variables, dev server per worktree, parallel agent 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.

Which worktree a command acts on

wt finds the repository from the working directory, and the worktree from the command's own arguments. Two rules cover every case:

1. A command that names a branch already names its worktree. Worktrees are addressed by branch name, so wt switch <branch>, wt remove <branch>, wt step diff --branch <branch>, and wt config state marker set --branch <branch> act on that branch's worktree no matter which worktree you run them from. Every such argument also accepts the worktree's own path, for the cases a branch cannot name — a second checkout of the same branch, or a detached worktree (which marker still rejects, since it keys state by branch name).
2. -C <path> moves the working directory, not the worktree selection. Reach for it when the repository lookup is what's wrong: a different repository; a command that acts on the current worktree and takes no branch argument (wt merge, wt step rebase|squash|push — their [TARGET] is the merge target, not a worktree); or a caller whose working directory isn't inside a repository at all, such as an agent hook the host pins elsewhere.

Layering -C on top of a branch argument names the same worktree twice. From inside the alpha worktree of a repo that also has beta:

wt step diff --branch beta                    # ✓ the branch argument selects the worktree
wt -C ../repo.beta step diff --branch beta    # ✗ says beta twice

wt switch --create beta                       # ✓ --base already defaults to the default branch
wt -C ../repo switch --create beta            # ✗ -C adds nothing; you are already in that repo

Two types of configuration

Worktrunk uses two config files with different scopes and permission models:

User config (~/.config/worktrunk/config.toml, never checked into git) holds personal preferences: LLM integration, worktree path templates, command settings, user hooks. Treat it conservatively — propose changes and get consent before editing, never install tools on the user's behalf, and preserve the file's existing structure and comments. See reference/config.md.

Project config (<repo>/.config/wt.toml, checked into git) holds team-wide automation: hooks for the worktree lifecycle (pre-start, pre-merge, etc.). Edit proactively — changes are versioned and reversible via git. Comment why each hook exists, and warn the user before adding destructive commands (rm -rf, DROP TABLE), network fetches piped to shells, or sudo. See reference/hook.md.

Some requests span both: commit-message generation is user config, while the team's quality checks are project config.

Core workflows

Setting up commit message generation (user config)

Detect which tools are installed (which claude codex llm aichat); if none, recommend Claude Code. Take the exact command for the chosen tool from reference/llm-commits.md, propose the [commit.generation] change, and apply it after approval (wt config create first if no config exists). To verify, wt step commit --dry-run renders the prompt, runs the LLM, and prints the message without committing.

Configuring project hooks

Pick the hook type by when the command should run and whether it may block (10 types: 5 events × pre/post — full reference in reference/hook.md):

• Dependencies and env files a later step needs → pre-start (blocks creation)
• Dev servers, long builds, cache copying → post-start (background)
• Formatters, linters, type checks → pre-commit
• Tests that must pass before merging → pre-merge
• CI triggers, notifications → post-commit
• Deployment → post-merge
• Setup before branch resolution / terminal-IDE updates → pre-switch / post-switch
• Cleanup before/after removal (save artifacts; stop servers, remove containers) → pre-remove / post-remove

Derive the commands from the project itself (package.json scripts, Cargo.toml, pyproject.toml) and verify they run before adding them.

When a new hook must wait for an existing one, convert the entry to a pipeline; independent commands in a named table run concurrently:

# Pipeline: install completes before migrate starts
[[pre-start]]
install = "npm install"

[[pre-start]]
migrate = "npm run db:migrate"

# Concurrent: independent commands in one table
[pre-start]
install = "npm install"
env = "cp .env.example .env"

Test with wt switch --create test-hooks.

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#prompt-templates
• Configure command defaults → reference/config.md#command-config
• Set up personal hooks → reference/config.md#hooks

Project config tasks

• Set up hooks for new project → reference/hook.md
• Add hook to existing config → reference/hook.md#hook-forms
• Use template variables → reference/hook.md#template-variables
• Add dev server URL to list → reference/config.md#dev-server-url

Aliases & multi-worktree tasks

• Create a wt alias → reference/extending.md#aliases
• Run a command in every worktree → reference/step.md#wt-step-for-each
• Rebase every worktree (up-style) → reference/extending.md#recipe-rebase-every-worktree-onto-its-upstream
• Defer a template variable to a nested wt command → reference/extending.md#deferring-expansion-to-a-nested-wt-command

Key commands

# View all configuration
wt config show

# Create initial user config (LLM/commit setup: see reference/llm-commits.md)
wt config create

# Full config reference (subcommands, templates, env vars)
wt config --help