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.

Synopsis

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

Ignored files in the worktree are deleted with it.

What it reads and writes

Reads the team file and this machine's approval store (the file must be the approved one), the session's state (.agents/team.state.json), and git: the base branch, the branch names, and the worktree itself. With --session, the state of that session instead of team.session.

Writes .agents/team.log, .agents/team.state.json (one record under the session: the folder, the branch, the seat when --seat names one, and whether workspace.setup succeeded), and, with new, the worktree itself and the branch it cuts.

The folder is workspace.path with {repo} and {task} filled; the branch is workspace.branch with {kind} and {task} filled. new fetches the base's upstream when it has one, and starts from the local base, with a note in the log, when it doesn't. Nothing is created when the fetch fails.

Who may run it

The owner, the coordinator's seat, and the operator's seat. --file is the owner's alone, from a terminal outside herdr.

Flags

remove takes no --kind and no --seat.

Refusals

When setup fails, the folder is still printed on stdout before the refusal: the worktree is kept, recorded as setup: failed, and the exit code is 1.

Exit codes

• 0 — the worktree was created, or removed; its folder, or what was removed, is printed on stdout.
• 1 — refused: a rule above, whatever the caller, the file, the name or git says.
• 2 — the invocation or the team file can't be read.

Examples

format: 1
project: beacon
coordinator: claude-keeper
operator: claude-keeper

trust:
  - .
  - ../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

The project has a main for the branches to start from:

Sketch the layout

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

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

The branch pattern asks for a kind, so the command does:

$ team worktree new select-width ; echo "exit $?"
team worktree: --kind is required: the branch pattern is "{kind}/{task}"
exit 1

The task name is one path segment, and nothing else:

$ team worktree new "select width" --kind fix ; echo "exit $?"
team worktree: a task name is one segment of letters, digits, ".", "_" and "-", and it starts with a letter or a digit
exit 1

A good one creates the worktree and prints where it is:

$ team worktree new select-width --kind fix
../worktrees/beacon/select-width

The same task can't be open twice:

$ team worktree new select-width --kind fix ; echo "exit $?"
team worktree: "select-width" is already recorded
exit 1

A commit that lives only in the worktree keeps it in place:

-C ../worktrees/beacon/select-width commit --allow-empty -m "Measure the pane"

$ team worktree remove select-width ; echo "exit $?"
team worktree: commits on no remote branch:
  <sha> Measure the pane
exit 1

A worktree with nothing to lose goes, and its branch stays:

$ team worktree new tidy-logs --kind chore
../worktrees/beacon/tidy-logs

$ team worktree remove tidy-logs
removed tidy-logs; the branch chore/tidy-logs is kept