Verbs

agentproto worktree

agentproto worktree ls      [--repo <dir>] [--status] [--json]
agentproto worktree new     <slug> [--repo <dir>] [--base <ref>] [--branch <name>]
                                   [--root <dir>] [--no-setup] [--json]
agentproto worktree rm      <path> [--repo <dir>] [--base <ref>] [--keep-branch] [--force]
                                   [--discard-untracked] [--discard-modified] [--json]
agentproto worktree archive <path> [--repo <dir>] [--base <ref>] [--keep-branch] [--force] [--json]
agentproto worktree gc      [--repo <dir>] [--apply] [--salvage-dirty]
                                   [--include-detached] [--noise <path,...>]
                                   [--active-minutes <n>] [--json]

Create, inspect, and tear down git worktrees. A pure local shell over @agentproto/worktree — no daemon required.

new provisions under a single worktrees.root so worktrees stop sprawling across hand-picked parents. rm, archive, and gc are deliberately root-agnostic on the other side: they take an explicit <path> and derive everything from that path's own git metadata, so they can also tear down worktrees new didn't create.

worktrees.root

Resolved with the same precedence as every other knob (flag > env > config > default):

Source
--root <dir>flag on new
AGENTPROTO_WORKTREES_ROOTenv
worktrees.root~/.agentproto/config.json
~/.agentproto/worktreesdefault

Subverbs

ls

Lists the repo's worktrees. The plain form parses git worktree list --porcelain — a fast local path, no forge round-trip.

FlagDefaultDescription
--repo <dir>cwdAny dir inside the repo; the main repo root is derived from it.
--statusfalseRun the status engine per entry — adds tree/integration/liveness axes, provenance, and a reclaim/salvage/hold class. Needs gh/GITHUB_TOKEN (memoised in ~/.agentproto/worktree-verdicts.json).
--jsonfalseEmit the entries as JSON.

new <slug>

Creates a worktree at <worktrees.root>/<repoName>/<slug> and writes a creation-provenance marker into its private gitdir.

FlagDefaultDescription
--repo <dir>cwdRepo to cut the worktree from.
--base <ref>origin/mainRef the branch is cut from.
--branch <name>wt/<slug>Branch to create.
--root <dir>(see above)Override worktrees.root for this run.
--no-setupfalseSkip the repo's declarative lifecycle entirely — agentproto.json's setup hooks and worktree.depsCmd/worktree.linkPaths defaults, and the local, gitignored <repo>/.agentproto/worktree.json's depsCmd/linkPaths/copyGlobs/cloneGlobs/writeFiles defaults.
--jsonfalseEmit the provisioned descriptor as JSON.

rm <path>

The honest plain-destructive verb. Stops the worktree's services, runs its committed teardown hooks, then removes it — and refuses a dirty tree unless the flag matching the class of change present authorizes it.

FlagDefaultDescription
--repo <dir>(from <path>)Repo that owns the worktree.
--base <ref>origin/mainRef whose committed teardown hooks run.
--keep-branchfalseAlways keep the branch. Without it the branch is deleted only when its tip is proven merged into base (the branch gc ladder); an unmerged branch is kept and the output says so.
--forcefalseDelete the branch even when it is not proven merged.
--discard-untrackedfalseAuthorize discarding unignored untracked files.
--discard-modifiedfalseAuthorize discarding modified tracked files.
--jsonfalseEmit {"removed":path,"branch":str|null} as JSON.

archive <path>

Salvage-then-remove. Snapshots the worktree's uncommitted state to ~/.agentproto/worktree-salvage/ (a changes.patch, a copy of every untracked file, and a MANIFEST.json) before running the same removal as rm with both discard flags granted — so nothing still on disk is lost. If the salvage step fails, nothing is removed.

The snapshot covers uncommitted state only. Committed work lives on the branch, which archive keeps unless its tip is proven merged into base (or --force is given). The decision, with its reason and the number of commits present on no remote, is printed and recorded in MANIFEST.json as branchDecision (written before the removal runs, so it is the intended outcome). A detached HEAD has no branch to keep; only its tipSha is recorded.

FlagDefaultDescription
--repo <dir>(from <path>)Repo that owns the worktree.
--base <ref>origin/mainRef whose committed teardown hooks run.
--keep-branchfalseAlways keep the branch (see above for the default).
--forcefalseDelete the branch even when it is not proven merged.
--jsonfalseEmit {"archived":path,"branch":…,"salvageDir":path,"branchDecision":…} as JSON.

gc

Classifies every linked worktree, then prints the plan. Dry run by default — nothing is touched without --apply.

ClassDefinition--apply does
reclaim(merged or fresh) + clean + idle, or a clean unpushed worktree whose only commits are mechanical dependency bumps (chore(deps) / fix(deps) subjects and the diff touches only lockfiles + package.json), or a clean, idle worktree whose branch content is provably in base by the branch gc ladder (squash-, patch- or content-merged — never for an open PR or an offline forge), or an integrated, idle worktree whose dirty paths provably carry no work (reason dirty-no-work: an emptied checkout, only turbo's managed AGENTS.md block, or changes byte-identical to base)Removes it (plain, non-force git worktree remove — refuses if the tree turned dirty since the plan was made) and deletes its branch. For dirty-no-work, restores exactly the proven paths first (git checkout HEAD -- / unlink).
salvagemerged + dirty, where the dirt is not provably work-free, and not written to in the last 15 minutesNothing, unless --salvage-dirty — then archives it (snapshot, then remove).
holdeverything else, including a fresh or merged branch with uncommitted work that is not provably work-free, and any worktree whose own git index was written within the last --active-minutes (recent activity — someone is working in it)Never touched, with or without flags.
FlagDefaultDescription
--repo <dir>cwdRepo to sweep.
--applyfalseExecute the plan instead of printing it.
--salvage-dirtyfalseAlso archive salvage-class worktrees.
--include-detachedfalseAccepted for compatibility; no longer widens anything. A clean, idle detached worktree is reclaimed by default, but only when its HEAD is proven in base (ancestor, squash, patch, or the head of a merged PR); otherwise it holds.
--noise <path,...>.opencode/package-lock.jsonWorktree-relative paths whose dirt is known noise: a worktree dirty only on these counts as clean, and removal restores them before a plain non-force remove. --noise "" disables.
--active-minutes <n>60Recent-activity window in minutes: a worktree whose own git index mtime is younger than this holds with reason recent-activity instead of reclaiming/salvaging. 0 disables the guard.
--jsonfalseEmit the plan (or the outcomes, with --apply) as JSON.

Between plan and apply, each entry is re-checked: one that reclassified, became recently active, or vanished is aborted rather than acted on stale.

Examples

# What's out there, and what shape is it in
agentproto worktree ls
agentproto worktree ls --status

# Cut a worktree for a branch off origin/main
agentproto worktree new my-feature
agentproto worktree new hotfix --base origin/release --branch fix/urgent

# Tear one down (refuses if dirty)
agentproto worktree rm ~/.agentproto/worktrees/myrepo/my-feature

# Keep the uncommitted work, then remove
agentproto worktree archive ~/.agentproto/worktrees/myrepo/my-feature

# Sweep: look first, then act
agentproto worktree gc
agentproto worktree gc --apply --salvage-dirty

Spawning an agent straight into a worktree

agent_start takes a worktree field so a spawn isolates itself without a separate worktree new first: worktree: true provisions one (branch wt/<slug> cut from origin/main, slug auto-minted from the session label) and lands the session in it; worktree: { slug, base } pins either. Provisioning (git worktree add plus the repo's own setup hooks, which can run minutes) now returns immediately by default — the session descriptor comes back right away with status "starting", and the resolved cwd is backfilled once the tree is ready. Poll the session's status: it flips to "running" on success, or "error" with a readable lastError on failure — it never sits in "starting" forever. Pass worktree: { async: false } for the old blocking contract (wait for the tree before agent_start returns); wait: true falls back to that same synchronous path automatically (there's no first-turn output to block on otherwise), and combining wait: true with an explicit async: true is rejected outright. It bites only for a root spawn whose cwd is inside a git repo — a spawn made through an orchestrator inherits its parent's tree, and a cwd outside any repo spawns plain.

The daemon can force the behaviour with worktrees.isolation in ~/.agentproto/config.json (or AGENTPROTO_WORKTREES_ISOLATION): always isolates every root spawn, never turns it off (and rejects an explicit worktree), on-request (default) honours the field. The provisioned tree is not auto-removed on session exit — it holds the agent's work; reclaim it with rm / archive / gc above.

Provisioning concurrency

The heavy part of provisioning (depsCmd, cloneGlobs/copyGlobs, and the worktree.setup hooks) is throttled by a daemon-wide scheduler, so a burst of agent_start({worktree}) spawns can no longer run five pnpm installs against one store at once. At most worktrees.provisionConcurrency (default 2, 0 = unlimited; env AGENTPROTO_WORKTREES_PROVISION_CONCURRENCY) heavy segments run at a time; the rest queue FIFO, fair across callers (a parent that already holds a slot goes behind one that holds none). git worktree add and other cheap steps are never queued, and a provisioning with no heavy phase skips the queue entirely. See config-schema for provisionConcurrencyByRepo and the optional provisionLoadFactor load guard.

While a spawn waits, agentproto sessions shows starting queued #2, and agent_sessions_list / session_list carry provisioning: { state: "queued" | "running", position, phase, startedAt }. The daemon also emits session:provisioning events (queued, started, phase, done).

Killing a starting session cancels its provisioning: a queued entry is dropped, and a running install has its whole process tree terminated (SIGTERM to the process group, SIGKILL after a grace period), so no orphaned pnpm survives. A cancelled provisioning removes the half-made worktree and branch; a provisioning that merely fails keeps its worktree for inspection, as before.

Boot timeouts and setup output

A hung or very slow worktree.setup / depsCmd can no longer leave a session in starting forever with nothing to read. Once the spawn holds its slot (queue wait does not count), two bounds apply to the heavy segment:

  • Stall: no output for stallTimeoutMs (default 120000, 2 min). Output from the hook resets the clock, so a 13-minute install that keeps printing is fine.
  • Hard cap: maxMs (default 1800000, 30 min) for the whole segment, output or not.

When a bound trips, the hook's whole process tree is killed (SIGTERM to the process group, SIGKILL after a grace period) and the session ends in error with a reason naming the phase, the elapsed time and the last 20 output lines (also in lastError). The worktree is kept for inspection, like any failed setup. 0 disables a bound. Set them per spawn with agent_start({ worktree: { slug, stallTimeoutMs, maxMs } }), or daemon-wide with worktrees.provisionStallTimeoutMs / worktrees.provisionMaxMs (env AGENTPROTO_WORKTREES_PROVISION_STALL_TIMEOUT_MS / AGENTPROTO_WORKTREES_PROVISION_MAX_MS); per-spawn beats env beats config beats the default.

While provisioning runs, the hook's stdout/stderr is streamed into the starting session's output (agent_output, lines prefixed [setup] / [deps], with ── provisioning: phase X ── banners), and daemon.log gets a [worktree] line for each start, phase change and failure.

Two limits: the queue lives in the daemon, so agentproto worktree new (its own short-lived process) throttles only against itself, not against the daemon's spawns; and the synchronous agent_start path (worktree: { async: false } or wait: true) is throttled and emits events but has no session row yet, so it shows no provisioning field and cannot be cancelled mid-provision.

See also