Skip to content

aidenlx/zotlit / .agents/skills/worktrunk

worktrunk

Verified

Guidance for Worktrunk (the `wt` CLI) — git worktree management, hooks, and config. Load when working out which worktree a `wt` command will act on, or reaching for the global `-C <path>` to target one; editing .config/wt.toml or ~/.config/worktrunk/config.toml; adding, modifying, or debugging hooks (post-merge, post-start, pre-commit, pre-merge, post-switch, etc.); configuring commit message generation or command aliases; or troubleshooting wt behavior. Also answers general worktrunk/wt questions.

FileKindSize
SKILL.mdskill md11.2 KB
reference/claude-code.mdmarkdown7.0 KB
reference/code-signing.mdmarkdown4.9 KB
reference/config.mdmarkdown49.9 KB
reference/extending.mdmarkdown12.0 KB
reference/faq.mdmarkdown20.4 KB
reference/hook.mdmarkdown20.4 KB
reference/list.mdmarkdown30.6 KB
reference/llm-commits.mdmarkdown8.2 KB
reference/merge.mdmarkdown7.0 KB
reference/remove.mdmarkdown7.4 KB
reference/shell-integration.mdmarkdown8.3 KB
reference/step.mdmarkdown30.8 KB
reference/switch.mdmarkdown13.3 KB
reference/tips-patterns.mdmarkdown20.5 KB
reference/troubleshooting.mdmarkdown6.4 KB
reference/worktrunk.mdmarkdown8.1 KB

reference/config.md

View on GitHub
# wt config

Manage user & project configs. Includes shell integration, hooks, and saved state.

## Examples

Install shell integration (required for directory switching):

```console
$ wt config shell install
```

Create user config file with documented examples:

```console
$ wt config create
```

Create project config file (`.config/wt.toml`) for hooks:

```console
$ wt config create --project
```

Show current configuration and file locations:

```console
$ wt config show
```

## Configuration files

| File | Location | Contains | Committed & shared |
|------|----------|----------|--------------------|
| **User config** | `~/.config/worktrunk/config.toml` | Worktree path template, LLM commit configs, etc | ✗ |
| **Project config** | `.config/wt.toml` | Project hooks, dev server URL | ✓ |

Organizations can deploy a system-wide config file for shared defaults — run `wt config show` for the platform-specific location.

**User config** — personal preferences:

```toml
# ~/.config/worktrunk/config.toml
worktree-path = ".worktrees/{{ branch | sanitize }}"

[commit.generation]
command = "MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --safe-mode --setting-sources='user' --system-prompt=''"
```

**Project config** — shared team settings:

```toml
# .config/wt.toml
[pre-start]
deps = "npm ci"

[pre-merge]
test = "npm test"
```

<!-- USER_CONFIG_START -->
# User Configuration

Create with `wt config create`. Values shown are defaults unless noted otherwise.

Location:

- macOS/Linux: `~/.config/worktrunk/config.toml` (or `$XDG_CONFIG_HOME` if set)
- Windows: `%APPDATA%\worktrunk\config.toml`

## Worktree path template

Controls where new worktrees are created.

**Available template variables:**

- `{{ repo_path }}` — absolute path to the repository root (e.g., `/Users/me/code/myproject`. Or for bare repos, the bare directory itself)
- `{{ repo }}` — repository directory name (e.g., `myproject`)
- `{{ owner }}` — primary remote owner path (may include subgroups like `group/subgroup`)
- `{{ remote_repo }}` — repository name in the primary remote URL, without `.git` (e.g., `myproject`); differs from `{{ repo }}`, the directory on disk, when a clone was renamed
- `{{ branch }}` — raw branch name (e.g., `feature/auth`)
- `{{ branch | sanitize }}` — filesystem-safe: `/` and `\` become `-` (e.g., `feature-auth`)
- `{{ branch | sanitize_db }}` — database-safe: lowercase, underscores, hash suffix (e.g., `feature_auth_x7k`)
- `{{ branch | codename(2) }}` — deterministic friendly name from a ~1.26M-combo pool (e.g., `malleable-opah`)

This is a smaller set than [the variables hooks and aliases get](https://worktrunk.dev/hook/#template-variables).

**Examples** for repo at `~/code/myproject`, branch `feature/auth`:

Default — sibling directory (`~/code/myproject.feature-auth`):

```toml
worktree-path = "{{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}"
```

Inside the repository (`~/code/myproject/.worktrees/feature-auth`):

```toml
worktree-path = "{{ repo_path }}/.worktrees/{{ branch | sanitize }}"
```

Friendly branch-derived names (`~/code/myproject.malleable-opah`):

```toml
worktree-path = "{{ repo_path }}/../{{ repo }}.{{ branch | codename(2) }}"
```

Friendly names with branch identity in a parent directory (`~/code/worktrees/feature-auth/malleable-opah`):

```toml
worktree-path = "{{ repo_path }}/../worktrees/{{ branch | sanitize }}/{{ branch | codename(2) }}"
```

Centralized worktrees directory (`~/worktrees/myproject/feature-auth`):

```toml
worktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"
```

By remote owner path (`~/development/max-sixty/myproject/feature/auth`):

```toml
worktree-path = "~/development/{{ owner }}/{{ repo }}/{{ branch }}"
```

Bare repository cloned to `~/code/myproject/.git` (`~/code/myproject/feature-auth`):

```toml
worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"
```

`~` expands to the home directory. Relative paths resolve from `repo_path`.

## LLM commit messages

Generate commit messages automatically during merge. Requires an external CLI tool.

### Claude Code

```toml
[commit.generation]
command = "MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --safe-mode --setting-sources='user' --system-prompt=''"
```

### Codex

Create `~/.codex/worktrunk-commit-instructions.txt` containing just `.` (no newline). Accepting Worktrunk's first-run Codex setup creates the file for you.

```toml
[commit.generation]
command = "codex exec -m gpt-6-luna -c model_reasoning_effort='none' -c project_doc_max_bytes=0 -c skills.max_context_tokens=1 -c agents.enabled=false -c features.goals=false -c web_search=disabled -c 'model_instructions_file=\"~/.codex/worktrunk-commit-instructions.txt\"' -c features.shell_tool=false -c features.unified_exec=false -c features.apps=false -c features.plugins=false --ephemeral --sandbox=read-only --json - | jq -sr '[.[] | select(.item.type? == \"agent_message\")] | last.item.text'"
```

### OpenCode

```toml
[commit.generation]
command = "opencode run -m anthropic/claude-haiku-5-5 --variant fast"
```

### llm

```toml
[commit.generation]
command = "llm -m claude-haiku-4.5"
```

### aichat

```toml
[commit.generation]
command = "aichat -m claude:claude-haiku-4.5 --code"
```

See [LLM commits docs](https://worktrunk.dev/llm-commits/) for setup and [Custom prompt templates](#custom-prompt-templates) for template customization.

## Command config

### List

Persistent flag values for `wt list`. Override on command line as needed.

```toml
[list]
summary = false    # Enable LLM branch summaries (requires [commit.generation])

full = false       # Show CI status and LLM summaries (--full)
branches = false   # Include branches without worktrees (--branches)
remotes = false    # Include remote-only branches (--remotes)

json-schema = 2    # JSON output schema: 2 (envelope, default) or 1 (bare array)

columns = ["branch", "status", "ci", "path"]   # Columns to show, in order — built-ins or custom headers (omit for the default set)

timeout-ms = 0     # Wall-clock budget for the entire collect phase; 0 disables
```

`columns` selects and orders the columns the `wt list` table and the `wt switch`
picker render; `--format json` ignores it and always emits every field. Omit it
for the default set. It is meant to drive a per-invocation
[alias](https://worktrunk.dev/extending/#aliases) (`wt --config-set 'list.columns=[…]' list`),
giving a named view without disturbing the default `wt list`. A static setting
works but pins one layout over a table that otherwise adapts to `--full` and
terminal width.

Valid built-in names:

- `branch` — The branch name
- `status` — Git status symbols, plus any user-defined status
- `working-diff` — Uncommitted line changes against `HEAD`, including untracked files (header `HEAD±`)
- `ahead-behind` — Commits ahead of and behind the default branch (header `main↕`)
- `branch-diff` — Line changes against the default branch (header `main…±`)
- `summary` — An LLM-generated summary of the branch
- `upstream` — Commits ahead of and behind the upstream tracking branch (header `Remote⇅`)
- `ci` — CI status of the head commit
- `path` — The worktree's path
- `url` — Dev-server URL from the `[list] url` template
- `commit` — The head commit's short hash
- `age` — Time since the last commit
- `message` — The head commit's subject

A selection mixes built-ins with [custom columns](#custom-columns), each named
by its `[list.custom-columns]` header (`columns = ["branch", "Ticket", "ci"]`),
and is exhaustive: only the listed columns render. Omit `columns` to keep the
default set, where custom columns append automatically.

Listing a column forces it on, space permitting: `ci` shows without `--full`. A
column whose data source is missing still stays hidden — `summary` needs an LLM
command (`[commit.generation]`), `url` needs a `[list] url` template.

#### Custom columns [experimental]

Custom columns add per-branch context to the `wt list` table. Each
`[list.custom-columns]` entry is a column: the key is the header, the template
renders each row's cell.

```toml
[list.custom-columns.Ticket]
template = "{{ vars.ticket }}"   # Required; the result is the cell text
width = 20                       # Optional max display width (default: 40)
priority = 9                     # Optional drop order when the terminal narrows;
                                 # lower = kept longer (default: 9, the URL band)
```

Templates may reference `{{ branch }}`, `{{ worktree_path }}`,
`{{ worktree_name }}` (empty for branch-only rows), and two per-branch
namespaces:

- `{{ vars.* }}` — values stored with
  [`wt config state vars set`](https://worktrunk.dev/config/#wt-config-state-vars).
- `{{ git.branch.* }}` — the branch's own git config under `branch.<name>.*`,
  read straight from `git config` (e.g. `{{ git.branch.jira }}` for a key you
  set yourself, or the git-native `description`). Git lowercases config variable
  names, so `branch.<name>.nvciShelf` reads as `{{ git.branch.nvcishelf }}`.

All standard filters work (`sanitize`, `hash_port`, `codename`, …). A row
where the template renders empty (e.g. a branch without the key) shows an
empty cell; a column that is empty for every row is dropped from the table.
`wt list --format json` includes the rendered values under
`items[].display.columns` in schema 2, or under `columns` in schema 1.

A `Jira` column reading a key kept in git config, and a `Summary` column
showing just the first line of the git-native branch description:

```toml
[list.custom-columns.Jira]
template = "{{ git.branch.jira }}"

[list.custom-columns.Summary]
template = "{{ git.branch.description | lines | first }}"
```

### Commit

Shared by `wt step commit`, `wt step squash`, and `wt merge`.

```toml
[commit]
stage = "all"      # What to stage before commit: "all", "tracked", or "none"
```

### Merge

Most flags are on by default. Set to false to change default behavior.

```toml
[merge]
squash = true      # Squash commits into one (--no-squash to preserve history)
commit = true      # Commit uncommitted changes first (--no-commit to skip)
rebase = true      # Rebase onto target before merge (--no-rebase to skip)
remove = true      # Remove worktree after merge (--no-remove to keep)
verify = true      # Run project hooks (--no-hooks to skip)
ff = true          # Fast-forward merge (--no-ff to create a merge commit instead)
```

### Remove

Persistent flag values for `wt remove`. Override on command line as needed.

```toml
[remove]
delete-branch = true   # Delete branch after removal (--no-delete-branch to keep)
```

### Switch

```toml
[switch]
cd = true          # Change directory after switching (--no-cd to skip)

[switch.picker]
pager = "delta --paging=never"   # Example: override git's core.pager for diff preview
preview = true                   # Show the preview panel on open (Alt-p toggles)
```

### Step

```toml
[step.copy-ignored]
exclude = []   # Additional excludes (e.g., [".cache/", ".turbo/"])
```

Built-in excludes (VCS metadata and tool-state directories) always apply; [the `wt step copy-ignored` docs](https://worktrunk.dev/step/#wt-step-copy-ignored) list them. User config and project config exclusions are combined.

### User aliases

Command templates that run as `wt <name>`. See the [Extending Worktrunk guide](https://worktrunk.dev/extending/#aliases) for usage and flags.

```toml
[aliases]
greet = "echo Hello from {{ branch }}"
url = "echo http://localhost:{{ branch | hash_port }}"
```

Aliases defined here apply to all projects. For project-specific aliases, use the [project config](https://worktrunk.dev/config/#project-aliases) `[aliases]` section instead.

### User project-specific settings

User config can include a `[projects]` table for project-specific settings — worktree layout, setting overrides, anything else — separate from the [project config](https://worktrunk.dev/config/#project-configuration) shared with teammates.

Entries are keyed by project identifier — `<host>/<owner>/<repo>` derived from the primary remote URL (no `.git` suffix; an explicit port other than SSH's default 22 stays with the host, as in `gitlab.example.com:2222/team/project`), or the canonical repo path when there is no remote. Run `wt config show` inside the repo to see the identifier for the current project; it appears in the `PROJECT CONFIG` section as `Identifier: …`.

Scalar values (like `worktree-path`) replace the global value; everything else (hooks, aliases, etc.) appends, global first. See [how the layers rank](https://worktrunk.dev/config/#precedence).

```toml
[projects."github.com/user/repo"]
worktree-path = ".worktrees/{{ branch | sanitize }}"
list.full = true
merge.squash = false
remove.delete-branch = false
pre-start.env = "cp .env.example .env"
step.copy-ignored.exclude = [".repo-local-cache/"]
aliases.deploy = "make deploy BRANCH={{ branch }}"
```

#### Matching several repositories with one entry

A key containing `*` matches any run of characters, `/` included, so one entry covers a whole host or namespace — including nested groups. `*` is the only wildcard; every other character, `.` among them, is literal.

```toml
# Every repository on a self-hosted forge whose hostname carries no brand
[projects."git.company.example/*"]
forge.platform = "gitlab"

# Everything under one namespace shares a layout
[projects."git.company.example/platform/*"]
worktree-path = ".worktrees/{{ branch | sanitize }}"
```

Every matching entry applies, least- to most-specific, following the rule above: a more specific entry — `git.company.example/platform/*` over `git.company.example/*` — wins where both set the same setting, while hooks and aliases from every matching entry all run, least-specific first. A literal key is the most specific of all; specificity is the count of non-`*` characters in the key. End a host-wide key with `/*` — a bare `git.company.example*` also covers hosts whose names merely start with that string. A remote on a non-default SSH port carries the port in its identifier, so its host-wide key is `git.company.example:2222/*`.

Entries in `approvals.toml` match the same way, so a hand-written pattern entry approves its commands for every repository it covers.

#### Forge platform and hostname

`forge` names the forge for the matched repositories — the user-level counterpart of the project config's [forge platform](https://worktrunk.dev/config/#forge-platform) block, for a self-hosted host whose name carries no `github`, `gitlab`, or `gitea` for detection to read.

```toml
[projects."git.company.example/*"]
forge.platform = "gitlab"                    # or "github", "gitea" (experimental), "azure-devops" (experimental)
forge.hostname = "api.git.company.example"   # API host, when the remote's own host isn't it
```

A repository's own `[forge]` block still wins over any entry here, field by field.

Hooks support all three [hook forms](https://worktrunk.dev/hook/#hook-forms). A table runs multiple commands concurrently; an array-of-tables pipeline runs steps in sequence:

```toml
# Single command
[projects."github.com/user/repo"]
post-start = "mise trust"

# Multiple commands, running concurrently
[projects."github.com/user/repo".post-start]
mise = "mise trust"
server = "npm run dev"

# Pipeline: steps run in sequence
[[projects."github.com/user/repo".post-start]]
install = "npm ci"

[[projects."github.com/user/repo".post-start]]
build = "npm run build"
server = "npm run dev"
```

### Custom prompt templates

Templates use [minijinja](https://docs.rs/minijinja/) syntax.

#### Commit template

Available variables:

- `{{ git_diff }}`, `{{ git_diff_stat }}` — diff content
- `{{ branch }}`, `{{ repo }}` — context
- `{{ recent_commits }}` — recent commit messages
- `{{ user_guidance }}`, `{{ project_guidance }}` — rendered append fragments (see [Appending to the prompt](https://worktrunk.dev/config/#appending-to-the-prompt))

Default template:

<!-- DEFAULT_TEMPLATE_START -->
```toml
[commit.generation]
template = """
<task>Write a commit message for the staged changes below.</task>

<format>
- Subject line under 50 chars
- For material changes, add a blank line then a body paragraph explaining the change
- Output only the commit message, no quotes or code blocks
</format>

<style>
- Imperative mood: "Add feature" not "Added feature"
- Match recent commit style (conventional commits if used)
- Describe the change, not the intent or benefit
</style>
{% if user_guidance %}
<user-guidance>
{{ user_guidance }}
</user-guidance>
{% endif %}{% if project_guidance %}
<project-guidance>
{{ project_guidance }}
</project-guidance>
{% endif %}
<diffstat>
{{ git_diff_stat }}
</diffstat>

<diff>
{{ git_diff }}
</diff>

<context>
Branch: {{ branch }}
{% if recent_commits %}<recent_commits>
{% for commit in recent_commits %}- {{ commit }}
{% endfor %}</recent_commits>{% endif %}
</context>

"""
```
<!-- DEFAULT_TEMPLATE_END -->

#### Squash template

Available variables (in addition to commit template variables):

- `{{ commit_details }}` — list of commits being squashed; each renders as its subject and exposes `.subject` / `.body`
- `{{ target_branch }}` — merge target branch

Default template:

<!-- DEFAULT_SQUASH_TEMPLATE_START -->
```toml
[commit.generation]
squash-template = """
<task>Write a commit message for the change in <diff>, which is everything the squash will record. <commits> lists what it folds in.</task>

<format>
- Subject line under 50 chars
- For material changes, add a blank line then a body paragraph explaining the change
- Output only the commit message, no quotes or code blocks
</format>

<style>
- Imperative mood: "Add feature" not "Added feature"
- Match the style of commits being squashed (conventional commits if used)
- Describe the change, not the intent or benefit
</style>
{% if user_guidance %}
<user-guidance>
{{ user_guidance }}
</user-guidance>
{% endif %}{% if project_guidance %}
<project-guidance>
{{ project_guidance }}
</project-guidance>
{% endif %}
<commits branch="{{ branch }}" target="{{ target_branch }}">
{% for detail in commit_details %}- {{ detail.subject }}
{% endfor %}</commits>

<diffstat>
{{ git_diff_stat }}
</diffstat>

<diff>
{{ git_diff }}
</diff>

"""
```
<!-- DEFAULT_SQUASH_TEMPLATE_END -->

#### Appending to the prompt

`template-append` adds personal conventions to the commit and squash prompts without restating the whole template:

```toml
[commit.generation]
template-append = """
- Explain the rationale in the body, not just the change
"""
```

See [the LLM commits guide](https://worktrunk.dev/llm-commits/#appending-to-the-prompt) for how the fragment renders and its project-config counterpart.

## User hooks

See [`wt hook`](https://worktrunk.dev/hook/) for hook types, execution order, template variables, and examples. User hooks apply to all projects; [project hooks](https://worktrunk.dev/config/#project-hooks) apply only to that repository.
<!-- USER_CONFIG_END -->
<!-- PROJECT_CONFIG_START -->
# Project Configuration

Project configuration lets teams share repository-specific settings — hooks, dev server URLs, and other defaults. The file lives in `.config/wt.toml` and is typically checked into version control.

To create a starter file with commented-out examples, run `wt config create --project`.

## Project hooks

Project hooks apply to this repository only. See [`wt hook`](https://worktrunk.dev/hook/) for hook types, execution order, and examples.

```toml
pre-start = "npm ci"
post-start = "npm run dev"
pre-merge = "npm test"
```

## Dev server URL

URL column in `wt list` (dimmed when port not listening):

```toml
[list]
url = "http://localhost:{{ branch | hash_port }}"
```

## Forge platform

The forge is read from the remote's hostname: any host carrying `github`, `gitlab`, or `gitea` anywhere in it, plus the Azure DevOps service domains. Name the forge explicitly for a host carrying none of those, such as a Forgejo instance at `forge.example.com`:

```toml
[forge]
platform = "github"  # or "gitlab", "gitea" (experimental), "azure-devops" (experimental)
hostname = "github.example.com"  # Example: API host (GHE / self-hosted GitLab)
```

When many repositories share one self-hosted host, name it once in user config with a [pattern-keyed `[projects]` entry](https://worktrunk.dev/config/#user-project-specific-settings) instead of repeating this block in each repo. A repository's own `[forge]` still wins, field by field.

## Commit-message append

`template-append` adds project-wide conventions to the LLM commit and squash prompts, shared so every teammate's LLM sees the same style guide:

```toml
[commit.generation]
template-append = """
- Use conventional commits (feat:, fix:, docs:, …)
- Reference the relevant issue ID in the body
"""
```

The first time the fragment is used (and whenever it changes), `wt` prompts the user to approve it — the same one-shot gate as project-defined hooks. Only `template-append` is honored from the project file; the LLM command and the main prompt template stay in [user config](https://worktrunk.dev/config/). See [the LLM commits guide](https://worktrunk.dev/llm-commits/#appending-to-the-prompt) for how the fragment renders.

## Copy-ignored excludes

Additional excludes for `wt step copy-ignored`:

```toml
[step.copy-ignored]
exclude = [".cache/", ".turbo/"]
```

Built-in excludes (VCS metadata and tool-state directories) always apply; [the `wt step copy-ignored` docs](https://worktrunk.dev/step/#wt-step-copy-ignored) list them. User config and project config exclusions are combined.

## Project aliases

Command templates that run as `wt <name>`. See the [Extending Worktrunk guide](https://worktrunk.dev/extending/#aliases) for usage and flags.

```toml
[aliases]
deploy = "make deploy BRANCH={{ branch }}"
url = "echo http://localhost:{{ branch | hash_port }}"
```

Aliases defined here are shared with teammates. For personal aliases, use the [user config](https://worktrunk.dev/config/#user-aliases) `[aliases]` section instead.
<!-- PROJECT_CONFIG_END -->

# Shell Integration

See [`wt config shell`](#wt-config-shell) for setup, activation, and current-shell diagnostics.

### First-run prompts

On first run without shell integration, Worktrunk offers to install it. On first commit without LLM configuration, it offers to configure a detected tool (`claude`, `codex`, `opencode`). Declining sets `skip-shell-integration-prompt` or `skip-commit-generation-prompt` automatically.

# Other

## Environment variables

All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.

### Naming convention

Config keys use kebab-case (`worktree-path`), while env vars use SCREAMING_SNAKE_CASE (`WORKTRUNK_WORKTREE_PATH`). The conversion happens automatically.

For nested config sections, use double underscores to separate levels:

| Config | Environment Variable |
|--------|---------------------|
| `worktree-path` | `WORKTRUNK_WORKTREE_PATH` |
| `commit.generation.command` | `WORKTRUNK_COMMIT__GENERATION__COMMAND` |
| `commit.stage` | `WORKTRUNK_COMMIT__STAGE` |

### Example: CI/testing override

Override the LLM command in CI to use a mock:

```console
$ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge
```

### Other environment variables

| Variable | Purpose |
|----------|---------|
| `WORKTRUNK_BIN` | Override binary path for shell wrappers; useful for testing dev builds |
| `WORKTRUNK_CONFIG_PATH` | Override user config file location |
| `WORKTRUNK_SYSTEM_CONFIG_PATH` | Override system config file location |
| `WORKTRUNK_PROJECT_CONFIG_PATH` | Override project config file location (defaults to `.config/wt.toml`); relative paths resolve from the worktree root |
| `WORKTRUNK_MAX_CONCURRENT_COMMANDS` | Max parallel git commands (default: 32). Lower if hitting file descriptor limits. |
| `WORKTRUNK_VERBOSE` | Verbosity level (`0`/`1`/`2`), like `-v`/`-vv` but applied everywhere — including shell completion, which no flag can reach |
| `RUST_LOG` | Logging directive (e.g. `worktrunk=debug`); overrides the verbosity baseline for what reaches stderr |
| `NO_COLOR` | Disable colored output ([standard](https://no-color.org/)) |
| `CLICOLOR_FORCE` | Force colored output even when not a TTY |

## Inline config overrides (`--config-set`)

`--config-set <toml>` overrides any user config key for a single invocation. The value is a TOML fragment, so arrays and tables work directly; the flag is global (works before or after the subcommand), repeatable, and a later `--config-set` replaces an earlier one for the same key.

```console
$ wt --config-set list.full=true list
$ wt step copy-ignored --config-set 'step.copy-ignored.exclude=["target", "dist"]'
```

This composes with aliases — an alias body can invoke `wt --config-set … <command>` to render a named view without changing the saved config.

## Precedence

Sources closer to the invocation rank higher (user config above system config), and within a config file a [project entry](https://worktrunk.dev/config/#user-project-specific-settings) outranks the global key of the same name. So `worktree-path` comes from the first of these that sets it:

1. `--config-set 'worktree-path = …'`
2. `WORKTRUNK_WORKTREE_PATH`
3. `[projects."github.com/owner/repo"]` in the config file
4. global `worktree-path` in the config file

A `--config-set` that names a project entry is both the highest layer and the most specific key, so it beats the same flag's global key:

```console
$ wt --config-set 'projects."github.com/owner/repo".worktree-path = "/tmp/scratch"' switch --create feature
```

Hooks, aliases and `step.copy-ignored.exclude` accumulate rather than replace, so an env-set hook and a project's hook both run.

## Command reference

```
wt config - Manage user & project configs

Includes shell integration, hooks, and saved state.

Usage: wt config [OPTIONS] <COMMAND>

Commands:
  shell      Shell integration setup
  create     Create configuration file
  show       Show configuration files & locations
  update     Update deprecated config settings
  approvals  Manage command approvals
  alias      Inspect and preview aliases
  plugins    Plugin management
  state      Manage internal data and cache

Options:
  -h, --help
          Print help (see a summary with '-h')

Global Options:
  -C <path>
          Working directory for this command

      --config <path>
          User config file path

      --config-set <toml>
          Override config with inline TOML, e.g. --config-set list.full=true (repeatable)

  -v, --verbose...
          Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug
          logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to
          apply the same level everywhere — including shell completion, which no flag can reach

  -y, --yes
          Skip approval prompts
```

# Subcommands

## wt config shell

Shell integration setup.

A subprocess cannot change its parent shell's directory. Shell integration defines a function that runs the Worktrunk binary, then changes the shell's directory when the command requests it. It also enables tab completion.

### Setup

```console
$ wt config shell install
```

Start a new shell after installation to load the wrapper. Invoke `wt` by name. Running a binary path or `git wt` bypasses the wrapper, so the shell's directory stays unchanged.

- `wt config shell install --help` — installation options
- `wt config shell init --help` — manual setup
- `wt config shell uninstall` — remove the integration

### Check the current shell

```console
$ wt config show
```

The SHELL INTEGRATION section reports whether the wrapper is active in the current session. Installation and activation are separate: a configured shell can still be running without the wrapper until its config is reloaded.

In bash, zsh, or fish, `type wt` checks that `wt` resolves to a function. In PowerShell, `Get-Command wt -All` lists the Function and Application definitions.

See [worktrunk.dev/shell-integration](https://worktrunk.dev/shell-integration/) for warning messages, installed files, and wrapper behavior.

### Command reference

```
wt config shell - Shell integration setup

Usage: wt config shell [OPTIONS] <COMMAND>

Commands:
  init        Generate shell integration code
  install     Write shell integration to config files
  uninstall   Remove shell integration from config files
  show-theme  Show output theme samples

Options:
  -h, --help
          Print help (see a summary with '-h')
```

## wt config shell init

Generate shell integration code.

Outputs shell code for `eval` or sourcing. Most users should run `wt config shell install` instead, which adds this automatically.

### Manual setup

For bash, fish, zsh, and PowerShell, add the matching line to the shell config. For Nushell, run the command to save the wrapper in its autoload directory.

Bash (~/.bashrc):
```console
$ eval "$(wt config shell init bash)"
```

Fish (~/.config/fish/config.fish):
```fish
wt config shell init fish | source
```

Zsh (~/.zshrc):
```zsh
eval "$(wt config shell init zsh)"
```

Nushell 0.113+ [experimental] — save to vendor autoload directory:
```console
$ wt config shell init nu | save -f ($nu.vendor-autoload-dirs | last | path join wt.nu)
```

PowerShell ($PROFILE):
```powershell
Invoke-Expression (& wt config shell init powershell | Out-String)
```

### Command reference

```
wt config shell init - Generate shell integration code

Usage: wt config shell init [OPTIONS] <bash|fish|nu|zsh|powershell>

Arguments:
  <bash|fish|nu|zsh|powershell>
          Shell to generate code for

          [possible values: bash, fish, nu, zsh, powershell]

Options:
      --cmd <CMD>
          Command name for shell integration (defaults to binary name)

          Use this to create shell integration for an alternate command name. For example,
          --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt
          conflicts with Windows Terminal.

  -h, --help
          Print help (see a summary with '-h')
```

## wt config shell install

Write shell integration to config files.

Appends an initialization line to bash, zsh, and PowerShell config files. For fish and Nushell, it replaces the autoloaded wrapper file; fish also gets a separate completion file. See [worktrunk.dev/shell-integration](https://worktrunk.dev/shell-integration/#files-created) for their locations.

### Examples

Install for all detected shells:
```console
$ wt config shell install
```

Install for specific shell only:
```console
$ wt config shell install zsh
```

Shows proposed changes and waits for confirmation before modifying any files.
Use --yes to skip confirmation.

### Command reference

```
wt config shell install - Write shell integration to config files

Usage: wt config shell install [OPTIONS] [bash|fish|nu|zsh|powershell]

Arguments:
  [bash|fish|nu|zsh|powershell]
          Shell to install (default: all)

          [possible values: bash, fish, nu, zsh, powershell]

Options:
      --dry-run
          Show what would be changed

      --cmd <CMD>
          Command name for shell integration (defaults to binary name)

          Use this to create shell integration for an alternate command name. For example,
          --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt
          conflicts with Windows Terminal.

  -h, --help
          Print help (see a summary with '-h')
```

## wt config shell uninstall

Remove shell integration from config files.

Removes Worktrunk initialization lines from bash, zsh, and PowerShell config files, and Worktrunk wrapper and completion files for fish and Nushell.

### Examples

Uninstall from all shells:
```console
$ wt config shell uninstall
```

Uninstall from specific shell only:
```console
$ wt config shell uninstall zsh
```

Skip confirmation prompt:
```console
$ wt config shell uninstall --yes
```

### Version tolerance

Uninstall removes every worktrunk-managed integration it finds, regardless of:
- Binary name it was installed under (`wt`, `git-wt`, …)
- Minor syntax variations between versions

### Command reference

```
wt config shell uninstall - Remove shell integration from config files

Usage: wt config shell uninstall [OPTIONS] [bash|fish|nu|zsh|powershell]

Arguments:
  [bash|fish|nu|zsh|powershell]
          Shell to uninstall (default: all)

          [possible values: bash, fish, nu, zsh, powershell]

Options:
      --dry-run
          Show what would be changed

  -h, --help
          Print help (see a summary with '-h')
```

## wt config show

Show configuration files & locations.

Shows config sources and checks for invalid TOML or list columns, misplaced or
deprecated keys, and commands awaiting approval. It renders every section
before failing; warnings exit zero.

### Full diagnostics

Use `--full` to run diagnostic checks:

```console
$ wt config show --full
```

This tests:
- **CI tool status** — Whether the CLI for the repository's forge (`gh`, `glab`, `tea`, or `az`) is installed and authenticated
- **Commit generation** — Whether the LLM command can generate commit messages
- **Version check** — Whether a newer version is available on GitHub

### Command reference

```
wt config show - Show configuration files & locations

Usage: wt config show [OPTIONS]

Options:
      --full
          Run diagnostic checks (CI tools, commit generation, version)

  -h, --help
          Print help (see a summary with '-h')

Output:
      --format <FORMAT>
          Output format

          [default: text]
          [possible values: text, json]
```

## wt config update

Update deprecated config settings.

Updates deprecated settings in user and project config files
to their current equivalents, removes deprecated keys that have no equivalent,
and reports each one. Shows a diff and asks for confirmation.

### Examples

Preview and apply updates:
```console
$ wt config update
```

Apply without confirmation:
```console
$ wt config update --yes
```

Write the migrated config to a file instead of updating in place:
```console
$ wt config update --output migrated.toml
```

Print the migrated config:
```console
$ wt config update --output=-
```

### Command reference

```
wt config update - Update deprecated config settings

Usage: wt config update [OPTIONS]

Options:
      --output <PATH>
          Output migrated config (- for stdout)

  -h, --help
          Print help (see a summary with '-h')
```

## wt config approvals

Manage command approvals.

Project hooks and project aliases prompt for approval on first run to prevent untrusted projects from running arbitrary commands. Approvals from both flows are stored together.

### Examples

List commands and their approval status for current project:
```console
$ wt config approvals list
```

Pre-approve all hook and alias commands for current project:
```console
$ wt config approvals add
```

Pre-approve without prompting, for a container or CI job:
```console
$ wt config approvals add --yes
```

Clear approvals for current project:
```console
$ wt config approvals clear
```

Clear only approvals for commands no longer in the project config:
```console
$ wt config approvals clear --stale
```

Clear global approvals:
```console
$ wt config approvals clear --global
```

Check whether an unattended run would stop for approval:
```console
$ wt config approvals list --format=json | jq -r .state
```

### How approvals work

Approved commands are saved to `~/.config/worktrunk/approvals.toml`. Re-approval is required when the command template changes or the project moves.

`--yes` bypasses the prompt, and what it leaves behind depends on the command it is passed to. On a command that runs project commands it grants consent for that run alone and records nothing, so the next run asks again. On `wt config approvals add` the record is the whole point, so the approvals are written — which is how an unattended environment pre-approves a project it has just cloned.

### Reading approval state

`wt config approvals list` reads the state without prompting or writing it, so an orchestrator can find out whether a non-interactive run will stop for approval before scheduling one. `--format=json` emits:

```json
{
  "state": "approval_required",
  "commands": [
    {"phase": "post-start", "name": "dev", "template": "npm run dev", "approved": false},
    {"phase": "pre-merge", "template": "cargo test", "approved": true}
  ],
  "stale": ["some removed command"]
}
```

`state` is `no_commands` (the project declares none), `approval_required` (at least one is unapproved), or `approved`. `name` is absent for an unnamed command and for the commit-template fragment.

`stale`, which can accompany any `state`, lists approvals whose command has since been edited or removed from the project config.

### Command reference

```
wt config approvals - Manage command approvals

Usage: wt config approvals [OPTIONS] <COMMAND>

Commands:
  list   List project commands and their approval status
  add    Store approvals in approvals.toml
  clear  Clear approved commands from approvals.toml

Options:
  -h, --help
          Print help (see a summary with '-h')
```

## wt config alias

Inspect and preview aliases.

Aliases are command templates configured in user (`~/.config/worktrunk/config.toml`) or project (`.config/wt.toml`) config and run as `wt <name>`. See the [Extending Worktrunk guide](https://worktrunk.dev/extending/#aliases) for the configuration format.

### Examples

Show every configured alias's template:
```console
$ wt config alias show
```

Show the template for `deploy`:
```console
$ wt config alias show deploy
```

Preview an invocation without running it:
```console
$ wt config alias dry-run deploy
$ wt config alias dry-run deploy -- --env=staging
```

### Command reference

```
wt config alias - Inspect and preview aliases

Usage: wt config alias [OPTIONS] <COMMAND>

Commands:
  show     Show an alias's template, or all aliases' templates
  dry-run  Preview an alias invocation with template expansion

Options:
  -h, --help
          Print help (see a summary with '-h')
```

## wt config state

Manage internal data and cache.

State is stored in `.git/` (config entries and log files), separate from configuration files.

### Keys

- **cache**: [Regenerable caches — CI status, summaries, git commands, hints, and the `wt switch -` target](https://worktrunk.dev/config/#wt-config-state-cache)
- **default-branch**: [The repository's default branch (`main`, `master`, etc.)](https://worktrunk.dev/config/#wt-config-state-default-branch)
- **marker**: [Custom status marker for a branch (shown in `wt list`)](https://worktrunk.dev/config/#wt-config-state-marker)
- **vars**: [Custom variables per branch](https://worktrunk.dev/config/#wt-config-state-vars)
- **logs**: [Operation and debug logs](https://worktrunk.dev/config/#wt-config-state-logs)

### Examples

Get the default branch:
```console
$ wt config state default-branch
```

Set the default branch manually:
```console
$ wt config state default-branch set main
```

Set a marker for current branch:
```console
$ wt config state marker set 🚧
```

Store arbitrary data:
```console
$ wt config state vars set env=staging
```

Drop the regenerable caches:
```console
$ wt config state cache clear
```

Show all stored state:
```console
$ wt config state get
```

Clear all stored state:
```console
$ wt config state clear
```

### Command reference

```
wt config state - Manage internal data and cache

Usage: wt config state [OPTIONS] <COMMAND>

Commands:
  get             Get all stored state
  clear           Clear all stored state
  cache           Regenerable caches
  default-branch  Default branch detection and override
  logs            Operation and debug logs
  marker          Branch markers
  vars            Custom variables per branch

Options:
  -h, --help
          Print help (see a summary with '-h')
```

## wt config state cache

Regenerable caches.

View or drop worktrunk's regenerable caches in one place. Everything here is rebuilt on demand — clearing only forces recomputation, never data loss.

### What's cached

- **CI status** — forge CI per branch (30–60s TTL), shown in [`wt list`](https://worktrunk.dev/list/#ci-status)
- **Summaries** — LLM-generated branch summaries (`wt list --full`, `wt switch` preview)
- **Git commands** — cached merge-tree, ancestry, diff-stat, and `wt switch` preview results
- **Hints** — one-time hints already shown in this repo
- **Previous branch** — the `wt switch -` target, re-recorded on the next switch

`cache clear` drops all of the above with no prompt. It re-shows one-time hints and forgets the `wt switch -` target until the next switch — both repopulate on their own.

Without a subcommand, runs `get`.

### Examples

Show cache contents:
```console
$ wt config state cache
```

Drop all caches:
```console
$ wt config state cache clear
```

### Command reference

```
wt config state cache - Regenerable caches

Usage: wt config state cache [OPTIONS] [COMMAND]

Commands:
  get    Show cache contents
  clear  Drop all caches

Options:
  -h, --help
          Print help (see a summary with '-h')

Output:
      --format <FORMAT>
          Output format (text, json) [default: text]
```

## wt config state default-branch

Default branch detection and override.

Useful in scripts to avoid hardcoding `main` or `master`:

```console
$ git rebase $(wt config state default-branch)
```

In a hook or alias template, prefer the `{{ default_branch }}` [template variable](https://worktrunk.dev/hook/#template-variables); `$(wt config state default-branch)` is for plain shell scripts.

Without a subcommand, runs `get`. `set` stores the override in the repository's local git config. The override adds no project file and applies to every linked worktree in the clone. `clear` then `get` re-detects. The branch must exist locally for `wt list` comparisons.

### Detection

Worktrunk detects the default branch automatically:

1. **Worktrunk cache** — Checks `git config worktrunk.default-branch`
2. **Git cache** — Detects primary remote and checks its HEAD (e.g., `origin/HEAD`)
3. **Remote query** — If not cached, queries `git ls-remote`, giving up after 10s
4. **Local inference** — If no remote, or the query was abandoned, infers from local branches

Once detected, the result is cached in `worktrunk.default-branch` — except a value inferred after the remote query was abandoned, so an outage can't make a guess permanent. A later change to `origin/HEAD` isn't picked up automatically: `wt config state` flags the mismatch, `set` adopts the new branch, and `clear` re-detects.

The local inference fallback uses these heuristics in order:
- If only one local branch exists, uses it
- For bare repos or empty repos, checks `symbolic-ref HEAD`
- Checks `git config init.defaultBranch`
- Looks for common names: `main`, `master`, `develop`, `trunk`

If none of these match, detection fails; set it explicitly with `wt config state default-branch set BRANCH`.

### Command reference

```
wt config state default-branch - Default branch detection and override

Usage: wt config state default-branch [OPTIONS] [COMMAND]

Commands:
  get    Get the default branch
  set    Set the default branch
  clear  Clear the default branch cache

Options:
  -h, --help
          Print help (see a summary with '-h')
```

## wt config state logs

Operation and debug logs.

View and manage log files — hook output, command audit trail, and debug diagnostics.

### What's logged

Three kinds of logs live in `.git/wt/logs/`:

#### Command log (`commands.jsonl`)

All hook executions and LLM commands are recorded automatically — one JSON object per line. Rotates to `commands.jsonl.old` at 1MB (~2MB total). Fields:

| Field | Description |
|-------|-------------|
| `ts` | ISO 8601 timestamp |
| `wt` | The `wt` command that triggered this (e.g., `wt hook pre-merge --yes`) |
| `label` | What ran (e.g., `pre-merge user:lint`, `commit.generation`) |
| `cmd` | Shell command executed |
| `exit` | Exit code (`null` for background commands) |
| `dur_ms` | Duration in milliseconds (`null` for background commands) |

The command log appends entries and is not branch-specific — it records all activity across all worktrees.

#### Hook output logs

Hook output lives in per-branch subtrees under `.git/wt/logs/{branch}/`:

| Operation | Log path |
|-----------|----------|
| Background hooks | `{branch}/{source}/{hook-type}/{name}.log` |
| Background removal | `{branch}/internal/remove.log` |

All `post-*` hooks (post-start, post-switch, post-commit, post-merge, post-remove) run in the background and produce log files. Source is `user` or `project`. Branch and hook names are sanitized for filesystem safety. Same operation on same branch overwrites the previous log. Removing a branch clears its subtree; orphans from deleted branches can be swept with `wt config state logs clear`.

#### Diagnostic files

| File | Created when |
|------|-------------|
| `trace.log` | Running with `-vv` |
| `trace.jsonl` | Running with `-vv` |
| `subprocess.log` | Running with `-vv` |
| `diagnostic.md` | Running with `-vv` |

`trace.log` is the human-readable trace of commands and their timings. `trace.jsonl` holds the same events as JSON lines, which `wt config state logs profile` summarizes into a performance report. `subprocess.log` holds full subprocess output. `diagnostic.md` is a bug-report bundle; `wt` prints a `gh gist create` command for it. All four are overwritten on each `-vv` run.

### Location

All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory.

### Structured output

`wt config state logs --format=json` emits three arrays — `command_log`, `hook_output`, `diagnostic`. Each entry carries a `file` (relative), `path` (absolute), `size`, and `modified_at` (unix seconds). Hook-output entries additionally expose `branch`, `source` (`user` / `project` / `internal`), `hook_type` (the `post-*` kind, or `null` for internal ops), and `name`. `branch` is the branch name, or `null` when no local branch writes to that log directory (e.g. the branch was deleted). `name` is the hook name as it appears in the log path, which differs from the configured name only when that contains characters unsafe in a filename. Filter with `jq` to pick out a specific entry.

### Examples

List all log files:
```console
$ wt config state logs
```

Query the command log:
```console
$ tail -5 .git/wt/logs/commands.jsonl | jq .
```

Path to one hook log (e.g. the `post-start` `server` hook for the current branch):
```console
$ wt config state logs --format=json | jq -r --arg branch "$(git branch --show-current)" '.hook_output[] | select([.branch, .source, .hook_type, .name] == [$branch, "user", "post-start", "server"]) | .path'
```

Logs for a specific branch:
```console
$ wt config state logs --format=json | jq '.hook_output[] | select(.branch == "feature/auth")'
```

Clear all logs:
```console
$ wt config state logs clear
```

### Command reference

```
wt config state logs - Operation and debug logs

Usage: wt config state logs [OPTIONS] [COMMAND]

Commands:
  get      List all log file paths
  profile  Performance profile from a trace
  clear    Clear all log files

Options:
  -h, --help
          Print help (see a summary with '-h')

Output:
      --format <FORMAT>
          Output format (text, json) [default: text]
```

## wt config state marker

Branch markers.

Custom status text or emoji shown in the `wt list` Status column.

### Display

Markers appear at the end of the Status column, after git symbols:

```console
$ wt list
  Branch       Status      HEAD±     main↕    main…±    Remote⇅  Commit    Age  Message
@ main             ^⇡                                    ⇡1      33323bc    1d  Initial commit
+ feature-api      ↑ 🤖              ↑1        +1                70343f0    1d  Add REST API endpo…
+ review-ui      ? ↑ 💬    +1        ↑1        +1                a585d6e    1d  Add dashboard comp…
+ wip-docs       ? –       +1                                    33323bc    1d  Initial commit

○ Showing 4 worktrees, 2 with changes, 2 ahead, hidden: Path
```

### Use cases

- **Work status** — `🚧` WIP, `✅` ready for review, `🔥` urgent
- **Agent tracking** — [Agent plugins](https://worktrunk.dev/claude-code/) set markers automatically
- **Notes** — Any short text: `"blocked"`, `"needs tests"`

### Storage

Stored in git config as `worktrunk.state.<branch>.marker`. Set directly with:

```console
$ git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'
```

Without a subcommand, runs `get` for the current branch. For `--branch`, use `get --branch=NAME`.

### Command reference

```
wt config state marker - Branch markers

Usage: wt config state marker [OPTIONS] [COMMAND]

Commands:
  get    Get marker for a branch
  set    Set marker for a branch
  clear  Clear marker for a branch

Options:
  -h, --help
          Print help (see a summary with '-h')

Output:
      --format <FORMAT>
          Output format (text, json) [default: text]
```

## wt config state vars

Custom variables per branch.

Store custom variables per branch. Values are stored as-is — plain strings or JSON.

### Examples

Set and get values:
```console
$ wt config state vars set env=staging
$ wt config state vars get env
```

Store JSON:
```console
$ wt config state vars set config='{"port": 3000, "debug": true}'
```

List all keys:
```console
$ wt config state vars list
```

Operate on a different branch:
```console
$ wt config state vars set env=production --branch=main
```

### Template access

Variables are available in [hook templates](https://worktrunk.dev/hook/#template-variables) as `{{ vars.<key> }}`. Use the `default` filter for keys that may not be set:

```toml
# .config/wt.toml
[post-start]
dev = "ENV={{ vars.env | default('development') }} npm start -- --port {{ vars.port | default('3000') }}"
```

JSON object and array values support dot access:

```console
$ wt config state vars set config='{"port": 3000, "debug": true}'
```
```toml
# .config/wt.toml
[post-start]
dev = "npm start -- --port {{ vars.config.port }}"
```

### Storage format

Stored in git config as `worktrunk.state.<branch>.vars.<key>`. Keys may contain only letters, digits, and hyphens.

### Command reference

```
wt config state vars - Custom variables per branch

Usage: wt config state vars [OPTIONS] <COMMAND>

Commands:
  get    Get a value
  list   List all keys
  set    Set a value
  clear  Clear a key or all keys

Options:
  -h, --help
          Print help (see a summary with '-h')
```
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall