team worktree

Creates and removes a task worktree: a second checkout of the project on a branch of its own, where one seat does one task. new cuts the branch from workspace.base, records the worktree in the session's state and prints its folder; remove deletes a worktree that holds nothing that would be lost, and keeps its branch. list prints every record that counts toward workspace.limit and writes nothing.

Synopsis

team worktree new <task> [--kind <kind>] [--seat <name>] [--session <name>] [--file <path>] [--json]
team worktree list [--session <name>] [--file <path>] [--json]
team worktree remove <task> [--branch <name>] [--session <name>] [--file <path>] [--json]

Ignored files in the worktree are deleted with it.

Flags

FlagValueEffect
<task>—one path segment: letters, digits, ., _, -, starting with a letter or a digit
--kind<kind>fills {kind} in workspace.branch; required when the pattern holds it, refused when it doesn't
--seat<name>records a declared seat in the worktree's record
--branch<name>remove only: the branch the worktree must be on; any other is refused
--session<name>the session the caller is judged in, instead of the team's own; new and remove read and write that session; the owner's alone
--file<path>deprecated: a legacy team file to read instead of the team's registry record; the owner's alone
--json—list prints its reading document; new and remove print their action envelope
--help, -h—the usage, and exit 0

remove takes no --kind and no --seat. new and list take no --branch. list takes no task, no --kind and no --seat.

Who may run it

CallerMay
the ownerrun it, from a terminal outside herdr; --session and --file are the owner's own
a run with no terminalnothing: team worktree: only the owner, the orchestrator or the operator runs this, from a terminal outside herdr or its own seat
the orchestrator's seat, the operator's seatrun it, on the pane the state records for that seat

Output and exit codes

OutcomeWhat is printedExit
the worktree was createdthe context line, then worktree <task>: created at <path>0
the recorded worktrees were listedthe context line, a TASK BRANCH PATH table (a missing folder's path ends (gone)), note: limit <n> (workspace.limit), then <n> worktree / <n> worktrees0
the worktree was removedthe context line, then removed <task>; the branch <branch> is kept — the branch the worktree is on, read from git, not from the state record0
the folder was already gonethe context line, then removed the record of <task>; its folder was already gone. No branch was deleted.0
new created the worktree and workspace.setup failedthe created line, then team worktree: setup failed on command <n> of <m>; the worktree is kept and recorded as setup: failed on stderr1
the run was refusedteam worktree: <reason>1
the invocation can't be readteam worktree: <problem> and the usage2
the team file can't be readteam worktree: line <n>: <message> (team worktree: <message> when the problem names no line)2

Under --json the same run is a team.worktree document: the reading document on list, the action envelope on new and remove, and the team.error document for a refusal — see the output contract.

Example

team config edit
format: 1
project: beacon
coordinator: claude-keeper
operator: claude-keeper

trust:
  - ~/.config/team/lobby
  - ~/Code/beacon
  - ~/Code/worktrees/beacon

workspace:
  mode: worktree
  path: ../worktrees/{repo}/{task}
  branch: "{kind}/{task}"
  base: main

seats:
  - role: coordinator
    name: claude-keeper
    label: coordinator
    cli: claude-code
    vendor: anthropic
    model: Claude Opus
    version: "5.5"
    launch: claude --model claude-opus-5-5

  - role: implementer
    name: claude-beacon
    label: implementer
    cli: claude-code
    vendor: anthropic
    model: Claude Opus
    version: "5.5"
    launch: claude --model claude-opus-5-5

A seat that isn't the orchestrator or the operator can't create one:

Terminal
 team worktree new select-width --kind fix ; echo "exit $?"
team worktree: only the owner, the orchestrator or the operator runs it; this call is claude-beacon
exit 1

The owner lists the records. This file sets no workspace.limit, so the limit is the default:

Terminal
 team worktree list ; echo "exit $?"
team beacon, session "beacon"
  TASK  BRANCH  PATH
note: limit 8 (workspace.limit)
0 worktrees
exit 0

--json is the same reading as a document, in the order the rows are printed:

Terminal
 team worktree list --json
{
  "schema": {
    "name": "team.worktree",
    "version": 1
  },
  "format": 1,
  "project": "beacon",
  "session": "beacon",
  "notice": null,
  "worktrees": [],
  "notes": [
    "limit 8 (workspace.limit)"
  ],
  "summary": {
    "worktrees": 0
  }
}