worktender-watch

worktender

A fleet of coding agents, one git worktree each — started on a GitHub issue, watched while they run, and cleaned up once the work has landed.

A herdr plugin. herdr is the terminal multiplexer coding agents run in; this plugin keeps its workspaces and your git worktrees pointing at the same reality.

Documentation is rendered at <https://steig.github.io/worktender/> — the same words as the markdown here, plus an overview and Patterns, which exist nowhere else.

The problem

Running several coding agents at once means running several worktrees. Making the directory is the easy half, and every tool does it — what nothing does is the round trip: an issue, a checkout named for it, an agent briefed on it, and a way to know when it is finished. start and gate are that half.

The other end is where it goes wrong. A few weeks in there are eleven checkouts on disk, some have a herdr workspace and some do not, some still have an agent sitting in them and some are ghosts, and the one you are least certain about is the one you least want to delete. So nobody deletes anything — and the honest reason is that no cleanup script has ever been trustworthy enough to run without reading its output line by line first.

worktender covers both ends. It starts an agent on an issue in a worktree of its own, and it reconciles git worktree list against herdr's workspaces and agents — adopting what herdr does not know about, staffing empty workspaces, and removing finished checkouts on the rule that ambiguity always keeps the worktree.

$ worktender ls
   BRANCH                    WORKSPACE  PANE    STATUS   SEQ   AGE  DIR
*  main                      w21        w21:p1  idle     1057  6m   worktender
   feat/1-reconcile-execute  w22        w22:p1  working  1055  8s   1-reconcile-execute
   fix/257-erasure-comments  w1K        w1K:p1  idle     812   3h   257-erasure-comments
   worktree/brave-valley     -          -       -        -     -    brave-valley-66f8

* marks the repository's main checkout; - means herdr has nothing for that worktree — the last row is a checkout with no workspace and no agent, which is exactly what sync picks up.

The directory column is the exception to that reading: it prints - when the directory is named after the branch, which is every worktree start made. It has something to say on the rows above, where it disagrees — a checkout adopted rather than created sits somewhere with no relation to its branch. --json carries both fields populated either way.

? marks a ghost: a workspace herdr is still holding open on a checkout git no longer has, which is what removing a directory out from under it leaves behind. It has no branch, because there is no checkout left to have one, and prune names it too. Naming is all either does. Closing a workspace is a different authority from removing a worktree: there is no checkout left to test for uncommitted work, so the strongest guard here is not unsatisfied but unavailable, and its panes may still hold a live agent whose conversation closing it would destroy. Close it in herdr once you are sure.

The pane is the one dispatch --pane takes.

The counter is herdr's own, and it is what idle cannot tell you: idle is the same cell for a worker that finished two seconds ago and one that never received its brief at all. Read it down the column rather than across a row — the third worktree above is 240-odd state changes behind the rest, which beside idle is the shape of a worker that stopped. It is a counter and not a clock because herdr exposes no timestamp on an agent at all; two readings and your own clock are what turn it into a duration, and what counts as stalled stays yours to decide.

Read the status beside it, always. It counts state changes, so a worker that stays in one state does not move it — and a worker thinking hard is exactly that. Frozen beside idle is finished-or-wedged, which is the question this column answers; frozen beside working is a long turn or a wedge and the column cannot say which. See Machine-readable output.

AGE is the clock herdr does not have, borrowed from the agent. herdr does name each agent's session, and Claude and Codex each append to a log file named after it as they work, so the log's last write is the agent's last activity: ~/.claude/projects/*/<session>.jsonl for Claude, ~/.codex/sessions/YYYY/MM/DD/rollout-*-<session>.jsonl for Codex. Only the file's modification time is read, never its contents. Any other agent, or a log that is not where it should be, leaves the cell - rather than a guess. The third worktree above has been idle for three hours, which is the reading the counter needed two listings for. It also moves during a turn that writes to its log, which the counter does not — so frozen beside working with a fresh age is a long turn, not a wedge.

Add --pr for a pull request column, which is off by default because it costs one gh call per branch:

$ worktender ls --pr
   BRANCH                    WORKSPACE  PANE    STATUS   SEQ   AGE  PR      DIR
*  main                      w21        w21:p1  idle     1057  6m   -       worktender
   feat/1-reconcile-execute  w22        w22:p1  working  1055  8s   OPEN    1-reconcile-execute
   fix/257-erasure-comments  w1K        w1K:p1  idle     812   3h   MERGED  257-erasure-comments

--reports adds a column carrying what the worker in each pane last told its coordinator, read back off the pane's own metadata — the same place report attached it and a gate reads it:

$ worktender ls --reports
   BRANCH                    WORKSPACE  PANE    STATUS   SEQ   AGE  REPORT   DIR
*  main                      w21        w21:p1  idle     1057  6m   -        worktender
   feat/1-reconcile-execute  w22        w22:p1  working  1055  8s   planned  1-reconcile-execute
   fix/257-erasure-comments  w1K        w1K:p1  idle     812   3h   done #4  257-erasure-comments

This is what a coordinator asks after its context is cleared, instead of having written the fleet down. It is in-flight state and not a history — metadata lives on the pane, so a released worker's last report is gone with it. The durable record of finished work is the pull request it named, which is --pr. The 200-character note is not in the table; it is untrusted text and it is in the JSON, where a consumer can decide what to do with it.

Agents in six repositories are six invocations and six directories to remember to visit, so --all-repos lists every repository herdr has a worktree workspace for — from anywhere, including outside a repository entirely. One that cannot be read says so on its own line and costs the others nothing:

$ worktender ls --all-repos
/Users/you/code/worktender
     BRANCH         WORKSPACE  PANE    STATUS   SEQ   AGE  DIR
  *  main           w21        w21:p1  idle     1057  6m   worktender
     77-cross-repo  w30        w30:p1  blocked  812   3h   -
/Users/you/code/lighthouse
     BRANCH  WORKSPACE  PANE   STATUS   SEQ   AGE  DIR
  *  main    w4         w4:p1  working  1061  2s   lighthouse

--pr is deliberately not available across repositories: the lookup runs in series and is scoped to one repository, so it would be both slow and asking the wrong repository.

--blocked keeps only the worktrees herdr reports a blocked agent in — the one status where the session has stopped and nobody but you can restart it. Working resolves itself and idle is finished or waiting; blocked sits there until somebody looks, which is why it is worth a question of its own:

$ worktender ls --all-repos --blocked
/Users/you/code/worktender
     BRANCH         WORKSPACE  PANE    STATUS   SEQ  AGE  DIR
     77-cross-repo  w30        w30:p1  blocked  812  3h   -

Repositories with nothing blocked are left out rather than drawn as empty headings, and nothing blocked anywhere says so instead of printing nothing. This is herdr's own agent status, not a worker's report --status blocked, which is worktender's own envelope and reaches only whoever gated on it. doctor names blocked worktrees too, rather than folding them into a count.

--sort orders the rows, which is what this listing wanted once people started watching it refresh in a pane rather than reading it once. Three fields, each sorted the way the column is actually read:

$ worktender ls --sort status
   BRANCH                    WORKSPACE  PANE    STATUS   SEQ   AGE  DIR
   77-cross-repo             w30        w30:p1  blocked  812   3h   -
*  main                      w21        w21:p1  idle     1057  6m   worktender
   feat/1-reconcile-execute  w22        w22:p1  working  1055  8s   1-reconcile-execute

• status puts the rows that want a person first — blocked, then idle, then done, then working, then the worktrees with no agent at all. That is the same reading as above rather than an alphabet: blocked sits there until somebody looks, idle is finished-or-wedged and is the coordinator's next move, and working resolves itself.
• seq is lowest first, because the counter only ever answers who stopped moving first. A high one is a worker herdr saw a moment ago.
• branch is alphabetical, with the branchless rows — ghosts, a detached head — at the bottom.

Rows that tie keep git's order, and no --sort keeps git's order entirely: a listing on a refresh loop should not reshuffle because one agent changed state. The order applies to --json too, so a consumer that asked for one gets it.

--no-header drops the label row for anything reading the table by line. The labels are on by default — the columns were unlabelled and the only place that said what they were was this file.

Every command takes --json if you are building on this rather than reading it. start, dispatch, report and gate — the four an agent orchestrates with — write their document on the failure paths too, and carry the exit code in it, because with --any a number cannot say which of five workers the gate was about. See Machine-readable output.

Everything is a subcommand of one binary. A standalone install puts it on PATH; a plugin install does not, because herdr owns that install. One line covers both — take what is on PATH, and fall back to asking herdr where it put it:

worktender=$(command -v worktender) || worktender=$(herdr plugin list --json \
  | jq -r '.result.plugins[] | select(.plugin_id == "steig.worktender") | .plugin_root')/bin/worktender

The same four reconcile commands are also registered as herdr actions, so a keybinding or menu can reach them — but that path is worse to script against, and this is what newcomers trip on first: invoke returns an invocation record, not the action's output. What the action printed is in the plugin log. Call the binary and the output is just on stdout.

Starting work on an issue

$ worktender start 42 --repo .
repository: /Users/you/code/thing
worktree: 42-fix-the-thing on origin/main (workspace w9, pane w9:p1)
fork point: origin/main is 31db5d1c9b7e4a02f6c1d8e5a3b90f2c4d6e8a10
done  staff  42-fix-the-thing  started claude as wt-42-fix-the-thing-016aab in w9:p1

briefed wt-42-fix-the-thing-016aab on #42; wait for it with:
  worktender gate --target wt-42-fix-the-thing-016aab --until done --require-pr

The agent name is not the branch name: herdr's agent namespace spans every repository at once, so the name carries a digest of the repository. Copy the line start prints rather than retyping it.

With several running, wait on all of them at once — the first to report releases the gate and it says which one:

$ worktender gate --any wt-42-fix-the-thing-016aab,wt-43-other-9c21f4 --until done
gate: waiting on wt-42-fix-the-thing-016aab (pane w9:p1), wt-43-other-9c21f4 (pane w10:p1) for status done, up to 15m
gate: wt-43-other-9c21f4 released after 4m12s (evidence: reported)

One command from an issue number to an agent working on it: it reads the issue title with gh, creates a worktree named for it, starts an agent in the new pane, and types a brief covering the whole round — read the issue, explore, change, test, self-review, open a PR, then report.

--repo because start creates a checkout, so it refuses to guess which repository — and unlike the reconcile commands it has no herdr action to be invoked through, because an action carries no arguments and start is nothing without its issue number. Flags may be written on either side of the number.

The brief is confirmed, not claimed. It is typed, then submitted with a separate Enter key event, and start waits for herdr to report the agent working. herdr answering ok means it delivered keystrokes, not that an agent received a prompt — and one Enter is not enough on its own, because herdr reports an agent started as soon as it recognises its prompt box, which a TUI draws seconds before it will act on a submit. Keys sent in that gap are discarded, so start offers the submit again every couple of seconds for as long as the agent stays idle. An agent still idle when that wait runs out fails the command.

Start several, then wait on the lot of them. start deliberately does not wait; gate is the other half.

--base <ref> forks from something other than the trunk, which is how a second slice starts while the first is still in review. The fork point is printed because a ref name is not a fixed point: this repository squash-merges, and a squash merge puts one new commit on the trunk and none of the base branch's own — so a stacked branch outlives its base only if someone kept the commit it was forked from. start prints it, and says so when the fork is not something the trunk already has. See Stacking on a branch that is still in review.

The brief does not carry the issue. It names it and tells the worker to run gh issue view, which reads the same text as tool output rather than as prose pasted into a prompt. Nothing an issue author writes reaches the brief at all — the title only survives as a branch name, already reduced to [a-z0-9-]. Nothing about the agent's autonomy is defaulted either: without --permission-mode, start changes nothing about what it may do.

A worktree seconds old is not ready for an agent. Its shell is still in direnv, nix or a login banner, and herdr refuses to start an agent against it — immediately, whatever timeout_ms the request carried. Staffing waits the pane out itself, for up to a minute, re-checking each time that nobody else has claimed the workspace meanwhile.

Install

Two routes, and which you want follows from whether you run herdr.

As a herdr plugin

The full command set — start, dispatch, gate, sync and the event hooks all need herdr, because herdr is what has workspaces and agents in it.

herdr plugin install steig/worktender

Read Trust first: this runs unsandboxed. With a Go toolchain present it compiles the source it just cloned, which is the stronger of the two install paths by a distance — what you can read is what you run. Without Go it falls back to the prebuilt release the manifest pins, checksummed.

herdr owns the install, so the binary is not on PATH. Resolve it once:

worktender=$(herdr plugin list --json \
  | jq -r '.result.plugins[] | select(.plugin_id == "steig.worktender") | .plugin_root')/bin/worktender

On its own, with neither herdr nor Go

curl -fsSL https://raw.githubusercontent.com/steig/worktender/main/scripts/install.sh | sh

One step, onto your PATH, no sudo. What you get is the half of worktender that was never herdr's — ls, prune and prune-apply, whose every removal rule is git and gh. Without herdr is what that costs.

The script resolves the newest release, downloads the binary for your platform, verifies it against the checksums.txt published alongside it, and installs to ~/.local/bin/worktender. A missing or mismatched checksum aborts; nothing unverified is ever made executable, and no failure path leaves a file behind.

Read it before you run it. Piping a script from the network into a shell is the trust being extended here, and the only thing that makes it a decision rather than a habit is having looked: <https://github.com/steig/worktender/blob/main/scripts/install.sh>.

Flags need sh -s --, because the script arrives down a pipe:

curl -fsSL https://raw.githubusercontent.com/steig/worktender/main/scripts/install.sh \
  | sh -s -- --version vX.Y.Z --dir ~/bin

• --version <vX.Y.Z> installs that release rather than resolving the newest. The default follows releases/latest, which is a moving pointer — pin it if you are reproducing an environment.
• --dir <path> puts the binary somewhere else. ~/.local/bin is the default because it is the user's own and on the default PATH of most distributions; the script says so when it is not on yours.

Upgrading is re-running the same line. A standalone install has no plugin checkout to fetch into and no build script to run, so worktender update — which is how a plugin install moves forward — says that plainly and points back here rather than doing something surprising. worktender doctor names the release you are on.

Windows has no POSIX sh. The release publishes worktender_windows_amd64.exe on the releases page; download and verify it yourself. Note that the degraded path needs HERDR_SOCKET_PATH on Windows regardless — see Without herdr.

Quickstart

# 1. install — see Install above, and read Trust before either line
herdr plugin install steig/worktender
# ...or, with no herdr and no Go:
#   curl -fsSL https://raw.githubusercontent.com/steig/worktender/main/scripts/install.sh | sh

# 2. resolve the binary. A standalone install is already on PATH and this line
#    just finds it; a plugin install is not, because herdr owns it.
worktender=$(command -v worktender) || worktender=$(herdr plugin list --json \
  | jq -r '.result.plugins[] | select(.plugin_id == "steig.worktender") | .plugin_root')/bin/worktender

# 3. see where you stand — and, if anything looks wrong, why.
#    doctor prints the path to itself, so you only need the jq once.
"$worktender" ls
"$worktender" doctor

# 4. adopt every orphan checkout, staff every idle workspace
"$worktender" sync

# 5. ask what looks finished — a DRY RUN, it removes nothing
"$worktender" prune                     # or: prune --repo /path/to/repo

# 6. only once you have read step 5's reasons
"$worktender" prune-apply

# 7. when doctor's version line says origin has moved past you
#    (a standalone install re-runs the installer instead; `update` says so)
"$worktender" update

Each of those four is also a herdr action — Worktender: list worktrees and friends — for reaching them from a keybinding or the plugin menu.

A few things worth knowing before step 5 surprises you:

• prune-apply deletes the local branch too, not just the checkout. It uses git branch -d and never -D, so a branch git considers unmerged survives and the output says how to force it. When origin/<branch> still exists that is reported rather than quietly left behind.
• gh must be authenticated, not merely installed. A merged pull request is the strongest authority this plugin accepts for "finished", and an unauthenticated gh is indistinguishable from "this branch has no PR" — so almost nothing is pruned, and the reasons look entirely ordinary while that happens. If prune keeps everything on a repository where you expect otherwise, check gh auth status first.
• The repository comes from herdr, not from where you are standing. Run as an action it resolves herdr's current workspace, which on a machine with several repositories open is routinely not the one you meant — a dry run inside a repository with four staffed worktrees, planning against a different project. Both halves print the root they resolved, so read the repository: line before acting on a plan. Pass --repo <path> to settle it: a path anywhere inside a repository resolves to its root, and a path that is not one is an error rather than a fallback.
• A worker that finished still holds its pane, because herdr frees an agent only when the pane goes away. Its worktree is kept, and the line says so and says what would remove it: prune-apply --release-agents closes the workspace and takes the agent with it. Pass the flag to prune as well, or the dry run describes a plan the apply will not carry out. An agent that is working is never released, flag or no flag.
• Prune reads remote-tracking refs, so run git fetch --prune first if you want a deleted upstream to count. A stale tracking ref reads as still present, which keeps the worktree — being out of date fails in the safe direction.
• sync converges over two passes, not one. A checkout adopted this pass has no workspace yet, so it cannot be staffed until the next. Running sync twice against a brand-new orphan is expected, not a bug.
• An install stays where it was installed. herdr has no plugin update, so nothing moves it forward on its own — one install sat four releases behind without a word. doctor's version line says when origin has moved past you and update fetches and rebuilds; the one thing neither can fix is that herdr plugin list keeps reporting the commit it recorded at install time. Step 7 cannot be how you first reach step 7, either — an install older than 0.6.0 has no update to run, so herdr plugin install steig/worktender is the way onto it, and the only way to correct that recorded commit. See Staying current.

Requirements

• herdr 0.7.0+ — this is a plugin; it talks to herdr over its local socket. Every measured behaviour behind report and gate was tested against 0.7.5 and nothing checks the running version, so prefer 0.7.5+ if you intend to use the hand-off pair. ls, prune and prune-apply do not need it — see Without herdr.
• git
• jq — for reading action output out of the plugin log, as above.
• gh, authenticated (optional) — only used to read pull request state. Without it, the only removals left are the ones a deleted upstream authorises (see How removal is decided), and a repository that uses pull requests will prune almost nothing.

The standalone installer needs none of herdr, Go or jq — only curl or wget, and sha256sum or shasum to verify what it downloaded with. It refuses rather than installing unverified if it cannot find one.

Without herdr

The removal rules are entirely git and gh — uncommitted work, commits base does not have, a deleted upstream, a merged pull request. None of them is a herdr question. So the commands built on them run with herdr absent:

$ worktender ls
   BRANCH                 WORKSPACE  PANE  STATUS  SEQ  AGE  DIR
*  main                   -          -     -       -    -    worktender
   120-json-stops-here    -          -     -       -    -    -
   worktree/brave-valley  -          -     -       -    -    brave-valley-66f8

The workspace, pane, agent, counter and age columns are empty because those facts do not exist, not because they could not be read — with no herdr there are no workspaces and no agents. prune and prune-apply reach exactly the verdicts they would otherwise, and prune-apply rem