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/list.md

View on GitHub
# wt list

List worktrees and their status.

Shows uncommitted changes, divergence from the default branch and remote, and optional CI status and LLM summaries.

The table renders progressively: branch names, paths, and commit hashes appear immediately, then status, divergence, and other columns fill in as background git operations complete.

## Full mode

`--full` adds the two columns that reach off-machine: [CI status](#ci-status) (forge pipeline pass/fail, over the network) and [LLM-generated summaries](#llm-summaries) of each branch's changes.

## Examples

List all worktrees:

```console
$ wt list
  Branch       Status      HEAD±     main↕    main…±    Remote⇅  Commit    Age  Message
@ feature-api  +   ↕⇡     +54   -5   ↑4  ↓1  +234  -24   ⇡3      6814f02   30m  Add API tests
^ main             ^⇅                                    ⇡1  ⇣1  41ee083    4d  Merge fix-auth: ha…
+ fix-auth         ↕|                ↑2  ↓1   +25  -11     |     b772e68    5h  Add secure token s…
+ fix-typos        _|                                      |     41ee083    4d  Merge fix-auth: ha…

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

Include CI status and LLM summaries:

```console
$ wt list --full
  Branch       Status      HEAD±     main↕    main…±    Summary                       Remote⇅  CI
@ feature-api  +   ↕⇡     +54   -5   ↑4  ↓1  +234  -24  Refactor API to REST archit…   ⇡3      #412
^ main             ^⇅                                                                  ⇡1  ⇣1  #
+ fix-auth         ↕|                ↑2  ↓1   +25  -11  Harden auth with constant-t…     |     #408
+ fix-typos        _|                                                                    |     #410

○ Showing 4 worktrees, 1 with changes, 2 ahead, hidden: Path, Commit, Age, Message
```

Include branches that don't have worktrees:

```console
$ wt list --branches --full
  Branch       Status      HEAD±     main↕    main…±    Summary                       Remote⇅  CI
@ feature-api  +   ↕⇡     +54   -5   ↑4  ↓1  +234  -24  Refactor API to REST archit…   ⇡3      #412
^ main             ^⇅                                                                  ⇡1  ⇣1  #
+ fix-auth         ↕|                ↑2  ↓1   +25  -11  Harden auth with constant-t…     |     #408
+ fix-typos        _|                                                                    |     #410
/ exp             /↕                 ↑2  ↓1  +137       Explore GraphQL schema and…
/ wip             /↕                 ↑1  ↓1   +33       Start API documentation

○ Showing 4 worktrees, 2 branches, 1 with changes, 4 ahead, hidden: Path, Commit, Age, Message
```

Output as JSON for scripting:

```console
$ wt list --format=json
```

## Columns

| Column | Shows |
|--------|-------|
| Branch | Branch name, elided with `…` past 32 characters; a detached worktree shows its short hash |
| Status | Compact symbols (see below) |
| HEAD± | Uncommitted changes, including untracked files: +added -deleted lines |
| main↕ | Commits ahead/behind default branch |
| main…± | Line diffs since the merge-base (three-dot) with the default branch |
| Summary | LLM-generated branch summary; requires `--full`, `summary = true`, and [`commit.generation`](https://worktrunk.dev/config/#commit) |
| Remote⇅ | Commits ahead/behind tracking branch |
| CI | PR/MR number colored by pipeline status; `--full` only |
| Path | Worktree directory |
| URL | Dev server URL from project config; dimmed if port is not listening |
| *(custom)* | User-defined [custom columns](#custom-columns) from `[list.custom-columns]` user config [experimental] |
| Commit | Short hash, abbreviated per `core.abbrev` |
| Age | Time since last commit |
| Message | Last commit message (truncated) |

The `main↕` and `main…±` headers keep the familiar `main` label in every repository.

The table sizes itself to the terminal. When the columns don't all fit, the least important go first — roughly right to left, since the order above runs from identity to nice-to-have — and the summary footer names them (`hidden: Commit, Age, Message`). A wider terminal brings them back. To pin a set rather than leave it to the width, name the columns in [`[list] columns`](https://worktrunk.dev/config/#list); `--format=json` carries every field at any width.

### Gutter

The leftmost column marks each row by physical presence, from most present to least:

| Symbol | Meaning |
|--------|---------|
| `@` | Current worktree |
| `^` | Primary worktree (the repo's home worktree) |
| `+` | Other worktree |
| `/` | Local branch without a worktree (`--branches`) |
| `\|` | Remote branch, not present locally until fetched (`--remotes`) |

### CI status

The CI column shows the branch's open PR/MR — `#3035` on GitHub, Gitea, and Azure DevOps, `!3035` on GitLab — colored by pipeline status, or a bare `#` when no number is available (e.g. branch workflows without a PR/MR). Green, blue, red, yellow, and gray show the pipeline state; magenta and cyan show the review state. [checks object](#checks-object) and [review states](#review-states) give the JSON form of each value:

| Indicator | Value | Meaning |
|-----------|-------|---------|
| `#` green | `"passed"` | All checks passed |
| `#` blue | `"running"` | Checks in progress |
| `#` red | `"failed"` | One or more checks failed |
| `#` yellow | `"conflicts"` | Merge conflicts with the target branch |
| `#` gray | `"no-ci"` | No PR/MR, or no checks configured |
| `⚠` yellow | `"error"` | CI status could not be fetched (expired login, rate limit, network, etc.) |
| `#` magenta | `"changes_requested"` | A reviewer requested changes |
| `#` cyan | `"pending"` | A review is required (e.g. branch protection) but not yet given |
| (blank) | `pr` and `checks` absent | Branch never pushed, forge CLI not logged in to the host, or no PR/MR and no branch workflow |

The two remaining review states have no indicator of their own: `"draft"` only dims the cell and `"approved"` leaves the color unchanged.

Changes requested (magenta) outranks running checks, while a required review (cyan) only recolors an otherwise green or gray branch. GitLab reports only the `"pending"` and `"draft"` review states.

CI cells are clickable links to the PR or pipeline page, and appear dimmed for a draft PR/MR (`"draft"`) or when unpushed local changes make the status stale (`checks.stale`). Results are cached for 30-60 seconds; use `wt config state cache` to view or clear.

### LLM summaries

Reuses the [`commit.generation`](https://worktrunk.dev/config/#commit) command — the same LLM that generates commit messages. Enable with `summary = true` in `[list]` config; requires `--full`. Results are cached until the branch's diff changes.

### Custom columns [experimental]

Each `[list.custom-columns]` entry in user config adds a column: the key is the header, the template renders each row's cell. Templates read two per-branch namespaces — `{{ vars.* }}`, stored with [`wt config state vars set`](https://worktrunk.dev/config/#wt-config-state-vars), and `{{ git.branch.* }}`, the branch's own git config under `branch.<name>.*` (a `jira` key you set yourself, or the git-native `description`) — useful for tracking what each of many (often agent-driven) branches is for:

```toml
# ~/.config/worktrunk/config.toml
[list.custom-columns.Ticket]
template = "{{ vars.ticket }}"
```

The [custom columns config](https://worktrunk.dev/config/#custom-columns) covers templates, widths, and drop priority.

## Status symbols

The Status column packs several subcolumns, left to right, each mapping to a schema-2 field in `--format=json` (schema 1 spells several of them differently — see [Schema 1](#schema-1)). Working-tree flags are independent and co-occur — any combination shows at once. The other subcolumns are mutually exclusive: each shows a single symbol, the highest-priority state in top-to-bottom table order, and is blank when nothing applies.

### Working tree

Independent flags from `git status`; several can show at once (e.g. `+!?`). Each maps to a boolean in the [changes object](#changes-object):

| Symbol | worktree.changes | Meaning |
|--------|------------------|---------|
| `+` | `staged` | Staged files |
| `!` | `modified` | Modified files (unstaged) |
| `?` | `untracked` | Untracked files |

`worktree.changes` also reports `renamed` and `deleted`, which have no dedicated symbol in the column.

### Worktree

An in-progress git operation, a worktree-location attribute, or a branch with no worktree. One symbol shows, highest priority first (`✘ > ↻ > ⊟ > ⊞ > ⊘ > ⚐ > /`):

| Symbol | JSON | Meaning |
|--------|------|---------|
| `✘` | `worktree.changes.conflicted` | Merge conflicts |
| `↻` | `worktree.operation` `"rebase"`, `"merge"`, `"cherry_pick"`, `"revert"`, `"bisect"` | A git operation is in progress; `git status` names it |
| `⊟` | `worktree.prunable` | Prunable (worktree directory or its `.git` gone) |
| `⊞` | `worktree.locked` | Locked worktree |
| `⊘` | `worktree.detached` | Detached HEAD |
| `⚐` | `worktree.duplicate_branch` | Branch checked out in more than one worktree |
| `⚐` | `worktree.branch_mismatch` | Worktree isn't at the path its branch implies |
| `/` | no `worktree` object | Branch without a worktree |

### Default branch

The single highest-priority state describing the branch's relation to the default branch; blank when none applies (a normal up-to-date branch). Each symbol is one `display.state` value:

| Symbol | display.state | Meaning |
|--------|---------------|---------|
| `^` | `"is_main"` | The main worktree (the repo's home worktree) |
| `∅` | `"orphan"` | No common ancestor with the default branch |
| `_` | `"empty"` | Same commit as the default branch, working tree clean — safe to remove; row dimmed |
| `⊂` | `"integrated"` | Content [integrated](https://worktrunk.dev/remove/#branch-cleanup) into the default branch or merge target via different history; the matching check is in `default_branch.integration.reason`; row dimmed |
| `✗` | `"would_conflict"` | Merging into the default branch would conflict (simulated with `git merge-tree`) and the branch isn't already integrated; with `--full`, the check includes tracked uncommitted changes |
| `–` | `"same_commit"` | Same commit as the default branch, but with uncommitted changes |
| `↕` | `"diverged"` | Both ahead of and behind the default branch |
| `↑` | `"ahead"` | Has commits the default branch doesn't |
| `↓` | `"behind"` | Missing commits the default branch has |

Rows are dimmed when [safe to delete](https://worktrunk.dev/remove/#branch-cleanup) — `_` (`"empty"`) or `⊂` (`"integrated"`).

### Remote

Relation to the tracking branch, derived from the `upstream.ahead` / `upstream.behind` counts; blank when there is no upstream:

| Symbol | upstream | Meaning |
|--------|----------|---------|
| `\|` | `ahead` 0, `behind` 0 | In sync with remote |
| `⇡` | `ahead` > 0 | Ahead of remote |
| `⇣` | `behind` > 0 | Behind remote |
| `⇅` | `ahead` > 0, `behind` > 0 | Diverged from remote |

### Marker

The last subcolumn shows the branch's marker, set with
[`wt config state marker set`](https://worktrunk.dev/config/#wt-config-state-marker) — usually an
emoji saying what the branch is for. It reads back as the item's `marker`
field.

### Placeholder symbols

These appear across all columns while the table is loading:

| Symbol | Meaning |
|--------|---------|
| `·` | Data is loading, or collection timed out |

---

## JSON output

`--format=json` emits schema 2 by default: the envelope format below. Set
`[list] json-schema = 1` to retain the original bare-array format.

### Schema 2

One envelope object. Items carry independent facts; rendered strings
(including the collapsed Status value) live under `display`:

```json
{
  "schema": 2,
  "repo": {
    "default_branch": "main",
    "forge": {"url": "https://github.com/org/repo", "provider": "github",
              "host": "github.com", "owner": "org", "name": "repo", "remote": "origin"}
  },
  "collected": {"ci": false, "summary": false},
  "items": [
    {
      "branch": "feature",
      "head": {"sha": "05a4a45d…", "short_sha": "05a4a45", "subject": "Add login page",
               "committed_at": "2025-01-01T08:00:00Z"},
      "worktree": {"path": "/home/user/repo.feature", "main": false, "current": true,
                   "previous": false, "detached": false, "branch_mismatch": false,
                   "duplicate_branch": false,
                   "changes": {"staged": false, "modified": true, "untracked": false,
                               "renamed": false, "deleted": false, "conflicted": false,
                               "diff": {"added": 10, "deleted": 2}}},
      "default_branch": {"ahead": 3, "behind": 1, "diff": {"added": 50, "deleted": 20},
                         "orphan": false, "integration": null, "merge_conflicts": false},
      "upstream": {"remote": "origin", "branch": "feature", "ahead": 0, "behind": 2},
      "display": {"state": "diverged", "symbols": "!↕", "statusline": "feature …"}
    }
  ]
}
```

How "no value" reads:

- **Absent** — nothing to report: not applicable (`worktree` on a branch-only
  row), not requested this run (the envelope's `collected` records what was),
  or determined-empty (no PR, no lock, not integrated).
- **`null`** — requested but not determined: a task timed out, a check was
  skipped, or a forge fetch failed. This is the JSON form of the table's `·`
  placeholder.

jq treats absent and `null` identically in path expressions, so filters need
no null checks; `has()` distinguishes the two when it matters.

Envelope fields:

| Field | Type | Description |
|-------|------|-------------|
| `schema` | number | Format version; always `2` |
| `repo` | object | `{default_branch, forge}` — the branch every `default_branch` object measures against (absent when detection failed), and forge metadata derived from the primary remote (absent when no remote URL parses; see [repo object](#repo-object)) |
| `collected` | object | `{ci, summary}` — which gated fact families this run requested, so an absent `pr`/`checks`/`summary` reads as "not requested" rather than "none" |
| `items` | array | One object per row: a worktree, a local branch, or a remote-only branch |

Item fields:

| Field | Type | Description |
|-------|------|-------------|
| `branch` | string/null | Branch name; null for a detached-HEAD worktree. Remote rows carry the bare name with the remote in `remote` |
| `remote` | string | Remote name, present only on remote-only branch rows |
| `head` | object/null | HEAD commit (see [head object](#head-object)); null for unborn branches |
| `worktree` | object | Worktree facts (see [worktree object](#worktree-object)); absent on branch-only rows |
| `default_branch` | object | Relation to the default branch (see [default_branch object](#default-branch-object)); absent on the default branch itself |
| `upstream` | object | Tracking branch (see [upstream object](#upstream-object)); absent when none is configured |
| `pr` | object | Open PR/MR (see [pr object](#pr-object)); collected with `--full` |
| `checks` | object | CI pipeline (see [checks object](#checks-object)); collected with `--full` |
| `dev_server` | object | `{url, listening}` from the project's `list.url` template; absent when not configured |
| `summary` | string | LLM branch summary; needs `--full`, `[list] summary = true`, and a `[commit.generation]` command |
| `marker` | string | Branch marker from [`wt config state marker`](https://worktrunk.dev/config/#wt-config-state-marker); absent when none is set |
| `vars` | object | Per-branch variables from [`wt config state vars`](https://worktrunk.dev/config/#wt-config-state-vars) |
| `display` | object | Rendered strings (see [display object](#display-object)) |

### head object

| Field | Type | Description |
|-------|------|-------------|
| `sha` | string | Full commit SHA (40 chars) |
| `short_sha` | string | Short commit SHA, abbreviated per `core.abbrev` (auto-extends for ambiguous prefixes) |
| `subject` | string/null | Commit subject (first line); null when not loaded, as for a prunable worktree |
| `committed_at` | string/null | Committer time, RFC 3339 UTC; null when not loaded |

### worktree object

Present only on worktree rows. The location attributes are independent, so they co-occur — see [Worktree](#worktree) for the symbols, which pick one:

| Field | Type | Description |
|-------|------|-------------|
| `path` | string | Worktree path |
| `main` | boolean | Is the main worktree |
| `current` | boolean | Is the worktree the command ran from |
| `previous` | boolean | Is the previous worktree (`wt switch -`) |
| `detached` | boolean | HEAD is detached |
| `locked` | object | `{reason}`; absent when not locked |
| `prunable` | object | `{reason}`; absent when git doesn't report the worktree prunable |
| `branch_mismatch` | boolean | Worktree isn't at the path its branch implies |
| `duplicate_branch` | boolean | Another worktree has the same branch checked out |
| `operation` | string/null | In-progress operation: `"merge"`, `"rebase"`, `"cherry_pick"`, `"revert"`, `"bisect"`; absent when none |
| `changes` | object/null | Working-tree state (see [changes object](#changes-object)) |

### changes object

The five change flags map to the [Working tree](#working-tree) symbols (`renamed` and `deleted` have none of their own):

| Field | Type | Description |
|-------|------|-------------|
| `staged` | boolean | Has staged files |
| `modified` | boolean | Has modified files (unstaged) |
| `untracked` | boolean | Has untracked files |
| `renamed` | boolean | Has renamed files |
| `deleted` | boolean | Has deleted files |
| `conflicted` | boolean/null | Tracked files carry merge conflicts |
| `diff` | object/null | Lines changed vs HEAD: `{added, deleted}` |

### default_branch object

Independent facts; the table's priority-collapsed symbol is `display.state`.

| Field | Type | Description |
|-------|------|-------------|
| `ahead` | number/null | Commits ahead of the default branch (null for orphans) |
| `behind` | number/null | Commits behind the default branch (null for orphans) |
| `diff` | object/null | Lines changed vs the default branch: `{added, deleted}` |
| `orphan` | boolean/null | No common ancestor with the default branch |
| `integration` | object/null | `{reason}` — which check found the content [integrated](https://worktrunk.dev/remove/#branch-cleanup) (see [integration reasons](#integration-reasons)); absent when determined not-integrated, null when undetermined (a check timed out or was skipped) |
| `merge_conflicts` | boolean/null | Merging into the default branch would conflict, simulated locally with `git merge-tree` |

### upstream object

`ahead` / `behind` drive the [Remote](#remote) divergence symbol:

| Field | Type | Description |
|-------|------|-------------|
| `remote` | string | Remote name (e.g., `"origin"`) |
| `branch` | string/null | Branch name on the remote |
| `ahead` | number | Commits ahead of remote |
| `behind` | number | Commits behind remote |

### pr object

| Field | Type | Description |
|-------|------|-------------|
| `number` | integer/null | PR/MR number |
| `url` | string/null | URL to the PR/MR page |
| `review` | string | Review state (see [review states](#review-states)); absent when the forge reports no review signal |
| `mergeable` | boolean/null | False when the forge reports conflicts, null otherwise |
| `repo` | object | Structured metadata for the repository the PR/MR targets, the upstream for fork PRs (see [repo object](#repo-object)); absent when the URL doesn't parse |

### checks object

| Field | Type | Description |
|-------|------|-------------|
| `status` | string/null | `"passed"`, `"running"`, or `"failed"`; null when a conflicts report masks it |
| `source` | string | `"pr"` (PR/MR) or `"branch"` (branch workflow) |
| `stale` | boolean | Local HEAD differs from remote (unpushed changes) |

Three [CI status](#ci-status) values have no `checks.status` of their own, because the shape of `pr` and `checks` reports them: a fetch error (`⚠`) makes both null, no CI leaves `checks` absent, and merge conflicts leave `checks.status` null with `pr.mergeable` false.

### dev_server object

| Field | Type | Description |
|-------|------|-------------|
| `url` | string | Dev server URL from project config |
| `listening` | boolean/null | Whether the URL's port is listening |

### display object

Presentation only — every value here renders facts that appear elsewhere in the item:

| Field | Type | Description |
|-------|------|-------------|
| `state` | string | The table's collapsed default-branch state (see [state values](#state-values)); absent when none applies |
| `symbols` | string | Raw status symbols without colors (e.g., `"!?↓"`) |
| `statusline` | string | Pre-formatted status with colors and links |
| `columns` | object | Rendered [custom column](#custom-columns) values keyed by header; empty cells omitted |

### repo object

`repo.forge` describes the local checkout's repository as derived from the primary remote. `pr.repo` describes the repository targeted by the PR/MR (for fork PRs, the upstream target).

| Field | Type | Description |
|-------|------|-------------|
| `url` | string | Repository web URL |
| `provider` | string | `"github"`, `"gitlab"`, `"gitea"`, `"azure-devops"`, or `"unknown"` |
| `host` | string | Repository web host |
| `owner` | string | Owner, organization, or namespace path |
| `name` | string | Repository name |
| `project` | string | Azure DevOps project name; absent for other providers |
| `remote` | string | Local remote name; present on `repo.forge`, absent from `pr.repo` |

### state values

The single highest-priority state describing the branch's relation to the default branch; absent when none applies (a normal up-to-date branch). Each value is one Default-branch symbol — see [Default branch](#default-branch) for the symbol and the full meaning of each value (`"is_main"`, `"orphan"`, `"empty"`, `"integrated"`, `"would_conflict"`, `"same_commit"`, `"diverged"`, `"ahead"`, `"behind"`).

### integration reasons

`default_branch.integration.reason` records which check matched. Checks run cheapest-first and the first match wins. See [Default branch](#default-branch) for symbols.

| Value | Meaning |
|-------|---------|
| `"same_commit"` | Branch HEAD is the default branch's commit |
| `"ancestor"` | Branch HEAD is an ancestor of the default branch, which has moved past it |
| `"no_added_changes"` | The three-dot diff (`main...branch`) is empty — no file changes beyond the merge-base |
| `"trees_match"` | Different history, but the branch's tree is identical to the default branch's |
| `"merge_adds_nothing"` | The branch has changes, but merging them leaves the default branch's tree unchanged (e.g. a squash merge where the target advanced on other files) |
| `"patch_id_match"` | The branch's squashed diff matches a single commit on the default branch (e.g. a GitHub/GitLab squash merge) |

### review states

`pr.review` is one of `"changes_requested"`, `"pending"`, `"draft"`, `"approved"`, absent when the forge reports no review signal. [CI status](#ci-status) shows how each renders. The vocabulary matches Claude Code's statusline `pr.review_state` field.

```console
# Current worktree path (for scripts)
$ wt list --format=json | jq -r '.items[] | select(.worktree.current) | .worktree.path'

# Branches with uncommitted changes
$ wt list --format=json | jq '.items[] | select(.worktree.changes.modified)'

# Worktrees with merge conflicts
$ wt list --format=json | jq '.items[] | select(.worktree.changes.conflicted)'

# Branches ahead of main (needs merging)
$ wt list --format=json | jq '.items[] | select(.default_branch.ahead > 0) | .branch'

# Integrated branches (safe to remove)
$ wt list --format=json | jq '.items[] | select(.display.state == "integrated" or .display.state == "empty") | .branch'

# Branches without worktrees
$ wt list --format=json --branches | jq '.items[] | select(.worktree == null) | .branch'

# Worktrees ahead of upstream (needs pushing)
$ wt list --format=json | jq '.items[] | select(.upstream.ahead > 0) | {branch, ahead: .upstream.ahead}'

# Stale CI (local changes not reflected in CI)
$ wt list --format=json --full | jq '.items[] | select(.checks.stale) | .branch'
```

A JSON Schema for the envelope is published at
[worktrunk.dev/schema/list-v2.json](https://worktrunk.dev/schema/list-v2.json).

### Schema 1

The original bare-array format — one object per row, no envelope — selected by
`[list] json-schema = 1`. Its fields all have a schema-2 home:

| Schema 1 | Schema 2 |
|----------|----------|
| `branch` | `branch` |
| `path` | `worktree.path` |
| `kind` | the row's shape — a `worktree` object means `"worktree"`, no `worktree` object means `"branch"` |
| `commit.sha`, `.short_sha`, `.message` | `head.sha`, `.short_sha`, `.subject` |
| `commit.timestamp` (Unix) | `head.committed_at` (RFC 3339 UTC) |
| `working_tree.staged`, `.modified`, `.untracked`, `.renamed`, `.deleted`, `.diff` | `worktree.changes.*` |
| `operation_state` `"conflicts"` | `worktree.changes.conflicted` |
| `operation_state` `"rebase"`, `"merge"`, … | `worktree.operation` |
| `main_state` | `display.state` |
| `integration_reason` | `default_branch.integration.reason` (snake_case, and it reports `"same_commit"` rather than folding it into `main_state`) |
| `main.ahead`, `.behind`, `.diff` | `default_branch.ahead`, `.behind`, `.diff` |
| `remote.name`, `.branch`, `.ahead`, `.behind` | `upstream.remote`, `.branch`, `.ahead`, `.behind` |
| `worktree.state` | `worktree.locked`, `.prunable`, `.duplicate_branch`, `.branch_mismatch` — independent, so they co-occur |
| `worktree.reason` | `worktree.locked.reason`, `worktree.prunable.reason` |
| `worktree.detached` | `worktree.detached` |
| `is_main`, `is_current`, `is_previous` | `worktree.main`, `.current`, `.previous` |
| `ci.status` | `checks.status`, plus the shapes described under [checks object](#checks-object) |
| `ci.source`, `ci.stale` | `checks.source`, `checks.stale` |
| `ci.number`, `ci.url`, `ci.review_state` | `pr.number`, `pr.url`, `pr.review` |
| `ci.repo`, `ci.repo_url` | `pr.repo`, `pr.repo.url` |
| `repo`, `repo_url` | the envelope's `repo.forge`, `repo.forge.url` |
| `url`, `url_active` | `dev_server.url`, `dev_server.listening` |
| `summary`, `vars`, `marker` | `summary`, `vars`, `marker` |
| `statusline`, `symbols`, `columns` | `display.statusline`, `display.symbols`, `display.columns` |

The envelope's `repo.default_branch` and `collected` have no schema-1 equivalent, and schema 2 separates "nothing to report" from "not determined" — see [How "no value" reads](#schema-2).

Missing a field that would be generally useful? Open an issue at https://github.com/max-sixty/worktrunk.

## Command reference

```
wt list - List worktrees and their status

Usage: wt list [OPTIONS]
       wt list <COMMAND>

Commands:
  statusline  Single-line status for the current worktree

Options:
      --format <FORMAT>
          Output format

          [default: table]
          [possible values: table, json]

      --branches
          Include branches without worktrees

      --remotes
          Include remote branches

      --full
          Show CI status and LLM summaries

      --progressive
          Show fast info immediately, update with slow info

          Displays local data (branches, paths, status) first, then updates with remote data (CI,
          upstream) as it arrives. Use --no-progressive to force buffered rendering. Auto-enabled
          for TTY.

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

Single-line status for the current worktree.

The line carries the same cells as the worktree's row in `wt list`. A stale CI status cache makes it reach the network for a second or two, so it fits a statusline the host renders in the background — Claude Code's, a `tmux` status bar — better than a prompt the shell blocks on. Want it fast enough for a synchronous prompt? Open an issue at https://github.com/max-sixty/worktrunk.

### Output formats

- `table` (default): `branch  status  HEAD±  main↕  main…±  Remote⇅  CI  URL`
- `json`: the current [`wt list --format=json`](https://worktrunk.dev/list/#json-output) schema — a one-item envelope by default, or a one-item array with `[list] json-schema = 1`
- `claude-code`: the `table` cells, preceded by `dir` and followed by `model  context  pace`

A cell with nothing to show is left out, so most lines are shorter than that. A line that overruns the terminal drops whole cells, least important first.

The CI reference links to its PR/MR, and a dev server URL carrying a port shows as `:3000` linking to the URL in full, dim until something answers on that port. Both are underlined terminal links.

### Claude Code mode

`--format=claude-code` reads JSON context from stdin (`.workspace.current_dir` is required; the rest are optional):

- `.workspace.current_dir` — working directory
- `.model.display_name` — model name
- `.context_window.used_percentage` — context usage (0–100), rendered as `🌔 65%`, the moon waning 🌕→🌑 as context fills
- `.rate_limits.{five_hour,seven_day}.used_percentage` — rate-limit window usage (0–100)
- `.rate_limits.{five_hour,seven_day}.resets_at` — window reset time (Unix epoch seconds)

The pace segment appears only when usage is likely to hit a rate limit before its window resets, and shows the higher-risk window: `2.9×(Tue–Tue 5pm)` reads as 2.9× the pace that would exactly fill that window. Above 90% used it shows usage instead of pace — `93%(Tue–Tue 5pm)`. Its color deepens from dim to yellow as more of the window would be spent capped.

[Claude Code statusline setup](https://worktrunk.dev/claude-code/#statusline-claude-code-only) has the `~/.claude/settings.json` entry that feeds this mode.

### Command reference

```
wt list statusline - Single-line status for the current worktree

Usage: wt list statusline [OPTIONS]

Options:
      --format <FORMAT>
          Output format

          Possible values:
          - table
          - json
          - claude-code: Claude Code statusline mode (reads context from stdin)

          [default: table]

  -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