wt treats machine-readable output as a first-class contract
(PLAN.md D13). Scripts, CI, and coding agents rely on exactly
these rules — they hold for every command, enforced by the test
suite.
- stdout carries data: paths, porcelain listings, config. Nothing else, ever.
- stderr carries everything meant for humans: progress notes, hook output, hints, errors.
So this is always safe:
tree="$(wt new feature/login)" # the tree's absolute path, nothing else
cd "$tree"| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | Error (git failure, unknown tree, invalid config). |
| 2 | Usage: unknown command, bad flag, wrong arguments. |
| 3 | Precondition failed: dirty tree, unpushed commits, name collision, already initialized. The repo is fine; the state blocks the action. |
| 4 | Not inside a git repository. |
Code 3 is the one worth branching on: it means "resolve something, then retry", never "wt is broken".
| Command | stdout |
|---|---|
wt new |
The new tree's absolute path, one line. |
wt path |
The resolved tree's absolute path, one line. |
wt go <q> |
The matched tree's absolute path, one line. Ambiguous: contenders on stderr, exit 3. No match: exit 1. |
wt ls |
One aligned row per tree. |
wt ls --porcelain |
One tree per line, three tab-separated fields: branch label, absolute path, comma-joined states (- when none). The field count never varies. |
bare wt, bare wt go |
Without a TTY on stdin and stderr: exactly the --porcelain listing, so agents never hang on the interactive picker. |
wt shell-init zsh |
The zsh integration script itself (it is the machine output — meant for eval). |
wt config |
Merged config as TOML; the two config file paths ride along as # comments, so the whole document stays parseable TOML. |
wt init |
Nothing (chatter on stderr). Non-interactive use requires --yes plus value flags; without a TTY, prompting is refused (exit 2) rather than hanging. |
wt done |
Nothing (chatter on stderr). |
wt sync |
Nothing (fetch, fast-forward, and per-tree behind report all ride stderr). |
wt claim |
The claimed slot's absolute path, one line. No free slot: exit 3. |
wt release |
Nothing (chatter on stderr). Not a slot / not claimed: exit 3. |
wt pool ls |
One aligned row per slot: slot, state (free, claimed, stale, unprovisioned), branch, detail. |
wt clean |
Nothing (every action, and -n's previews, ride stderr). |
wt status |
The overview table; --json for the machine shape below. |
wt doctor |
The check report; --json for the machine shape below. Exit 0 healthy, 3 when a fail-status check needs fixing; warn/info are advisory and never exit 3. Works outside a repository (repo checks simply absent). |
The claim/release loop for agents (see pool-mode.md):
slot="$(wt claim "$TICKET")" # a warm slot in seconds
cd "$slot" && …work…
wt release "$TICKET" # branch survives for the PR flowls, status, and doctor take --json: two-space-indented
JSON on stdout, nothing on stderr — except doctor's one-line
issue summary, which accompanies exit 3 on stderr in both output
modes. Fields marked omitempty are absent when zero/empty.
Free-text fields (note, symptom, cause, fix) are for
humans and may reword between releases; every other field name
and value is stable.
wt ls --json — an array of trees:
[
{
"branch": "feature/login",
"path": "/Users/you/acme.trees/feature-login",
"head": "0b7e…",
"locked": true,
"locked_reason": "keep me"
}
]Every field except path is omitted when false/empty — test
presence, not value. That includes branch (absent on detached
and bare trees) and head (absent on bare trees), not just the
boolean flags and reason strings.
wt status --json — the repo overview:
{
"mode": "pool",
"base": { "name": "main", "last_fetch": "2026-07-25T09:30:00Z", "stale": false },
"trees": [
{ "branch": "main", "path": "/Users/you/acme", "disk_kb": 1782579 }
],
"pool": {
"size": 2,
"slots": [
{ "slot": "slot-1", "state": "claimed", "branch": "PROJ-123",
"pid": 4242, "claimed_at": "2026-07-25T08:00:00Z", "note": "…" },
{ "slot": "slot-2", "state": "free" }
]
}
}base.last_fetch is absent until wt has fetched once;
disk_kb is absent when a tree could not be measured
(sizes are cached for up to an hour);
pool is absent in default mode.
wt doctor --json — the diagnostics:
{
"checks": [
{ "name": "git", "status": "ok", "symptom": "2.50.1" },
{ "name": "worktrees", "status": "fail",
"symptom": "1 registered tree gone from disk",
"cause": "a tree directory was deleted without telling git",
"fix": "wt clean" }
],
"issues": 1
}status is one of ok, info, warn, fail;
issues counts the fails and matches the exit code rule above.
Check names are stable identifiers: git, shell-shim,
repo (only when the repository itself cannot be resolved),
config, worktrees, branches, submodules, hooks-path,
trees-volume, leases (pool repos), update.
A porcelain line looks like:
feature/login /Users/you/acme.trees/feature-login -
main /Users/you/acme locked,prunable
Detached trees carry the literal branch label (detached).
hooks.setup runs via sh -c inside the new tree.
Both its stdout and stderr are forwarded to wt's stderr,
so a chatty install script can never corrupt the contract above.