team remove

Takes one seat out of the team: asks it to exit, waits for its pane to come back to its shell, closes its workspace, and edits the file so the seat is not started again. --keep leaves the seat in the file as stopped: true instead of taking it out. A seat that is busy — working, blocked at a prompt, or holding unsent text — is left as it is, unless its owner abandons it. Every other seat, and the session, are left alone.

Synopsis

team remove <name> [--keep] [--abandon] [--session <name>] [--file <path>]

What it reads and writes

Reads the team file, the session's state (.agents/team.state.json, for a temporary seat's record), and herdr: whether the session runs, its agents, each pane's screen and status, and the pane's foreground processes, which is how it knows the CLI has really exited. No approval is read: taking a seat out is not a change the owner has to approve.

Writes the team file (the seat's entry taken out, or stopped: true added to it), .agents/team.state.json (the seat's record is dropped), .agents/team.log, and, through herdr: the exit typed into the pane, the wait for its shell, and the workspace closed. A file edit that would not validate is refused before the seat is stopped, so a broken file never costs a live seat.

Who may run it

The owner, the coordinator's seat and the operator's seat. The coordinator's and the operator's own seats are the owner's alone to remove, and so is --abandon. --file is the owner's alone, from a terminal outside herdr.

Flags

What it prints

claude-beacon: stopped
removed claude-beacon

The seat's stop is the plan down prints for a seat, with its notes; the last line says what was done with the file:

A seat that doesn't leave cleanly is printed once with what stopped it, and remove exits 1: <seat>: its exit was not typed; left as it is, <seat>: timed out leaving its pane; left as it is, <seat>: its workspace did not close. The file is then not edited: the seat is still in the team.

Refusals

--abandon answers the last five: the seat is not asked anything, its workspace is closed as it is, and its pane's text is lost.

Exit codes

• 0 — the seat was stopped or was not running, and the file was edited.
• 1 — the run was refused, or the seat was left behind with the file untouched.
• 2 — the invocation, the team file or the state can't be read, or the edit would not validate.

Examples

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

workspace:
  mode: shared

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 mid-turn is not interrupted — its work would be lost — and remove says which state it was in:

$ team remove claude-beacon ; echo "exit $?"
team remove: claude-beacon is working; left as it is
exit 1

A permission prompt is the same: team never answers one, so it never closes a seat that waits at one.

$ team remove claude-beacon ; echo "exit $?"
team remove: claude-beacon is blocked at a prompt, which team never answers
exit 1

An implementer's seat may not remove anything — not even itself:

$ team remove claude-beacon ; echo "exit $?"
team remove: only the owner, the coordinator or the operator runs it; this call is claude-beacon
exit 1

The coordinator's seat may remove others, never itself, and --abandon is the owner's own, from a terminal outside herdr:

$ team remove claude-keeper ; echo "exit $?"
team remove: only the owner removes the coordinator's or the operator's seat; this call is claude-keeper
exit 1
$ team remove claude-beacon --abandon ; echo "exit $?"
team remove: only the owner abandons a seat, from a terminal outside herdr
exit 1

A temporary seat is recorded in the state, not in the file, so it is removed by the name add gave it — and --keep has nothing to keep. It comes before the seats the file declares change: taking a seat out of the file moves the limits the file defaults to, and add --temporary refuses a file that is no longer the approved one.

$ team add --temporary --like claude-beacon --until result:notes/result.md ; echo "exit $?"
claude-beacon-tmp-1: ready
exit 0
$ team remove claude-beacon-tmp-1 --keep ; echo "exit $?"
team remove: a temporary seat is not in the file; there is nothing to keep
exit 1
$ team remove claude-beacon-tmp-1 ; echo "exit $?"
claude-beacon-tmp-1: stopped
removed temporary claude-beacon-tmp-1
exit 0

--keep stops the seat and leaves its place in the file, for a seat that will come back:

$ team remove claude-beacon --keep ; echo "exit $?"
claude-beacon: stopped
stopped claude-beacon
exit 0
$ team add claude-beacon ; echo "exit $?"
claude-beacon: ready
exit 0

Without --keep the seat's entry goes with it, and a second remove has nothing to find:

$ team remove claude-beacon ; echo "exit $?"
claude-beacon: stopped
removed claude-beacon
exit 0
$ team remove claude-beacon ; echo "exit $?"
team remove: the team has no seat "claude-beacon"
exit 1

A name is required, and its absence stops at the usage line before the file is read:

$ team remove ; echo "exit $?"
team remove: a seat name is required
Usage: team remove <name> [--keep] [--abandon] [--session <name>] [--file <path>]
exit 2