Crew

Crew manages a team of AI agents, each running in a terminal session with a persona.

List Active Crew

$ metateam crew list
# or
$ metateam crew

Initialize a Crew

$ metateam crew init [NAME] [--force]

Creates crew state and seeds template-backed KB entries.

Use --force to re-sync matching template entries.

Start a Crew (Bootstrap)

$ metateam crew start [--client <CLIENT>]

Bootstraps the crew via a leader persona. --client overrides client selection (for example codex).

Launch the Dashboard With a Specific Lead Client

$ metateam --lead-client <CLIENT>

Summons the crew lead with the given client (claude, codex, agy, pi, opencode, grok) for that launch only. Three inputs decide a summoned agent's client, in order:

  1. the client named in the persona's KB profile;
  2. the Forced summon client setting (F12 → o), which overrides 1 for every persona;
  3. --lead-client, which overrides both — for the lead, on that one bootstrap summon.

Everyone summoned afterwards follows rules 1 and 2, and so does the lead if it is released and summoned again later: nothing stores the flag. An unrecognised client stops the launch and lists the supported ones rather than falling back to a different client.

Note that metateam crew start --client <CLIENT> is a different thing: it prefers a leader persona whose profile names that client, rather than forcing the client a persona runs on.

Summon an Agent

$ metateam crew summon <NAME> [MESSAGE] [--client <CLIENT>] [--backend <BACKEND>]

Agent names cannot contain spaces, tabs or other whitespace. Summon and registration reject such names before starting or installing an agent. Names are case-insensitive; spaces are not removed automatically.

--backend accepts tmux, mux or embedded. On Unix, an explicit mux request falls back to embedded with a warning.

On Windows, the default is mux when use_tmux is enabled and embedded otherwise. The mux session server owns its PTY; embedded sessions use the dashboard's PTY. A failed mux launch falls back to embedded only when the failure is proven to leave no session owner. The fallback reports its reason.

Configured client commands are parsed as an executable and options using Windows argument quoting. Quote paths and values containing spaces. Percent expressions such as %VAR% stay literal; shell operators such as & and | are rejected. Launch messages, model values, and effort values are passed as separate arguments without shell expansion.

Native .exe/.com programs and recognized npm .cmd launchers are supported. Npm launchers run through their interpreter directly, preserving interpreter options and preferring an interpreter installed beside the launcher. Custom batch, PowerShell, JavaScript, extensionless, or modified npm wrappers require configuring the native interpreter and script explicitly. Opaque batch launchers and explicit cmd.exe commands are unsupported; point to the underlying client executable. Unsupported wrappers produce an error. The dashboard creates the Windows client and registers its membership in one request. If registration fails, it terminates the newly created child and reports the error. Restart the dashboard after upgrading so it accepts the managed spawn request; older dashboards reject the new operation before starting a process. A malformed explicitly preferred client command reports an error. During fallback, unlaunchable candidates are logged and skipped so another configured client can run.

Register an Existing Agent

metateam crew register <NAME> accepts an optional --backend. An explicit backend or inherited METATEAM_CREW_BACKEND identifies the transport. Registration hooks that omit it preserve an existing registration's transport. A new registration without transport evidence is marked external.

External registration requires the actual client PID. Claude and Antigravity hooks find the client ancestor through shell wrappers; for a custom client, use metateam crew register <NAME> --client <CLIENT> --backend external --pid <CLIENT_PID>. Do not pass the PID of a hook or a short-lived shell. Registration errors are reported to the caller.

The communicator records external membership in .crew/external-agents.json, including the process creation identity. Its ten-second reconciliation loop removes confirmed dead or replaced processes and restores verified live clients after a dashboard restart, even while the client is idle. An unavailable observation cannot remove a registration or restore an unverified one. A different live process cannot claim the same external name; explicitly deregister the old owner first. Managed transport registration replaces the external claim. Explicit deregistration also removes the durable record. Stale instance tokens are harmless no-ops: only an accepted removal clears the launch workdir's readiness marker and writes removal history. Legacy runtime.json contains queued messages and compatibility attributes, not evidence of live external membership.

Registration does not create a message-delivery surface for a plain terminal. Messages to external registrations return an explicit transport error; use embedded, mux or tmux sessions for crew message delivery. Managed launches supply the backend automatically. An unavailable session observer is never treated as proof that registered sessions have ended. Reconciliation warnings use unified logging; unchanged failures remain quiet until the observation changes or recovers.

Release an Agent

$ metateam crew release <NAME>

Release removes durable membership before reporting success. For an external registration it removes crew membership without terminating the unowned terminal. Persistence failures are returned to the caller. Matching deregistration during graceful shutdown counts as successful release. A newer claim on the name causes an ownership conflict and remains untouched, even if it subsequently exits.

Send Messages

$ metateam crew message <TARGET> [MESSAGE] [--from <FROM>] [--file <FILE>...]

Target format:

Target Meaning
agent Agent in current crew
crew:agent Agent in another local crew
host:crew:agent Agent on a remote host
name1,name2 Multiple recipients
all Broadcast current crew
all-crews Broadcast all local crews
all-stations Broadcast all stations/crews/agents

Local and same-station file attachments are saved in each receiving crew's .crew/mail-board/ before that crew receives the message. A failed copy or copy worker fails that destination. Other destinations still receive their own delivery attempts. Existing filenames are preserved; copies use a different name on collision. A file already directly in the receiving mail-board is reused. Nested files are copied to the board root so each attachment notice names the saved file.

A failed attachment batch can leave earlier complete files in the destination board, but that destination receives no success notice. Source files that end before their advertised length or contain extra readable bytes are refused. Copying has no total filesystem-I/O deadline or source snapshot guarantee. A total delivery failure exits nonzero and prints no success mark. An accepted partial delivery retains the partial success mark and lists failed destinations. JSON output includes the delivery result and also exits nonzero on total failure. Broadcasts preserve accepted and failed members of partial deliveries. Same-station results qualify bare recipient names with their crew. Failures before recipient attempts identify the requested target or group. Empty, whitespace-only and comma-only targets are refused before attachment work or communicator calls. These copy rules describe local and same-station delivery; remote transport acceptance retains its existing meaning.

Tmux and embedded message delivery reject a busy or unavailable input guard before pasting or submitting anything. Embedded delivery holds the guard from paste through submission, so overlapping messages cannot merge into one prompt. Retry a refused message after the current delivery finishes or the protected operator draft ends. Operator typing, paste and keys arriving during an automated delivery are retained in order until its submission completes. That input remains an unsubmitted draft unless the operator also presses Enter. A pending draft blocks subsequent automated messages. The dashboard tracks drafts on Windows and Unix; idle draft guards expire after 60 seconds without character input. Deferred input is limited to 256 actions and 1 MiB per session; excess input returns an error to the caller. Automated delivery sends a second Enter 300 ms after the first, under the same input guard, to recover when the client ignores the first. This applies to ordinary messages and summons on every backend. A refused or failed first submission never triggers the second Enter.

Check Recent Messages

$ metateam crew inbox

Attach to an Agent Session

$ metateam crew attach <NAME>

Capture Agent Screen

$ metateam crew screen <NAME> [-n <LINES>] [--all] [-o <FILE>] [--no-trim]

Reset an Agent Context

$ metateam crew reset <NAME>

Resets the agent session context and asks it to recall the last session.

Personas

$ metateam crew persona list
$ metateam crew persona show <NAME>
$ metateam crew persona add <NAME>
$ metateam crew persona edit <NAME>
$ metateam crew persona export <NAME>
$ metateam crew persona import <FILE>
$ metateam crew persona delete <NAME>

Communication Instructions

$ metateam crew communication show
$ metateam crew communication edit

Client-Specific Instructions

$ metateam crew client-instructions show <CLIENT>
$ metateam crew client-instructions edit <CLIENT>

Workflow Record

$ metateam crew workflow show
$ metateam crew workflow edit
$ metateam crew workflow reset

Mission Record

metateam crew mission prints the exact bytes of .crew/mission.json, or {} when there is no mission. If someone hand-edits the file into an invalid record, the command still prints those bytes and exits nonzero so the file can be repaired. Use metateam crew mission set <VALUE> to validate and replace the record; VALUE can be inline JSON or - to read JSON from stdin. Setting {} deletes the mission. Mission readers and setters accept only regular files up to 64 MiB. Larger or nonregular files return an error. The limit also applies to stdin and the formatted record that the setter publishes.

The record is a JSON object with a nonblank title, an RFC 3339 started timestamp, and exactly one ordered array: tasks for a single lane or lanes for a mega-lane. Either array may be empty. The record may also carry a nonblank status line describing where the crew stands, with an RFC 3339 status_at time; status_at without status is rejected. Each task or lane has nonblank text and may have owner and artifact strings, an RFC 3339 done timestamp, or nested tasks. A lane may have its own started timestamp, even without children; below a lane, only a group (a task with nested tasks) may have started. Unknown fields are rejected. mission set fills a missing root started with the current time and stamps done: true with the current timestamp, including in lanes and nested tasks. It also stamps a missing status_at, except that an unchanged status text keeps the stamp it already has, so editing tasks does not reset the status age.

Every task, group, or lane has its own state. Omitted or false active means queued. "active": true means active. A done timestamp means done. Clear active before stamping that same item done; claiming both states is invalid. Any number of items anywhere in the tree can be active. Parent and child states are independent: a parent can stay active after its children finish, and a done parent can have an active descendant. No item becomes active automatically. The mission is complete only when every item has its own completion timestamp.

For a single lane, the setter can fill started:

$ metateam crew mission set '{"title":"Ship CLI help","tasks":[{"text":"Document Mission","active":true,"owner":"foundry","artifact":"manual/cli/crew.md"}]}'
$ metateam crew mission

For a nested mega-lane, pass readable JSON on stdin. The completed child is timestamped when set runs:

$ metateam crew mission set - <<'JSON'
{
  "title": "Platform release",
  "lanes": [
    {
      "text": "Alpha 1: CLI",
      "owner": "foundry",
      "tasks": [
        {"text": "Implement command", "done": true},
        {"text": "Review help", "active": true, "owner": "flint", "artifact": "manual/cli/crew.md"}
      ]
    },
    {
      "text": "Alpha 2: Dashboard",
      "tasks": [{"text": "Render Mission overlay", "active": true, "owner": "data"}]
    }
  ]
}
JSON

On an agent tab, F12, c toggles the Mission overlay; the dashboard's F12 help lists it as Toggle Mission panel.

The overlay expands branches with active items. Ancestors keep their own state; they do not inherit activity. It draws each active item's artifact directly below its declaring row. Short panels prioritize active rows in document order before optional artifact and context rows. They never show an artifact without its declaring row. status is pinned to the last row as Status 12m: ..., the age counting from status_at.

The dashboard messages the present local lead when it observes an invalid mission record, including at startup and while the panel is hidden. The message includes the file path and error. An unchanged acknowledged error does not send another message. A changed error or recovery to a valid or absent record rearms notification. If no lead is present, the dashboard retries when a lead joins. Delivery uses a five-second total I/O deadline. A refusal leaves notification pending. A timeout has an uncertain delivery outcome, so a retry can repeat a message whose acknowledgement was lost.

Dashboard Watchdog

$ metateam crew watchdog status
$ metateam crew watchdog on
$ metateam crew watchdog off

status reports the live dashboard watchdog timer as on or off. on/off toggle the same idle-leader nudge timer as F12, w in the dashboard runtime. The enabled state is not saved to .crew/settings.json; timeout and message configuration are still saved there. These commands require the matching crew dashboard communicator to be running.

Dashboard

$ metateam crew dashboard [--no-resize]

Opens the crew dashboard TUI.

Clear Crew State

$ metateam crew clear

Requires the dashboard communicator. It releases live members and removes durable external registrations, including candidates whose processes cannot currently be verified. Queued messages are preserved. If membership changes during the command or storage fails, clear reports an error instead of claiming the crew is empty.

Rename / Delete a Crew

$ metateam crew rename <NAME>
$ metateam crew delete <station:crew> [--force] [--yes]

crew delete target format is station:crew (example: devmac:atlas).

Observability

  • crew attach to observe an agent in real time
  • crew screen to capture terminal output programmatically
  • .crew/history.md for message/event history
  • .crew/mail-board/ for long-form reports

Antigravity (agy)

The default command is agy --dangerously-skip-permissions. Model and effort overrides use --model and --effort. Metateam adds the crew project root with --add-dir and passes the initial briefing with -i, including an explicit instruction to read CREW.md and START.md. agy creates the conversation only when it receives that prompt.

agy loads both GEMINI.md and AGENTS.md in each directory from its working directory to the git root. Each file is limited to 24,000 bytes. Managed summons write a short AGENTS.md that requires the agent to read the complete CREW.md and START.md. Existing ancestor instruction files also apply. Metateam removes stale instruction files only inside the generated persona directory; it does not change another project's parent instructions.

Reset sends /clear; release sends /exit. Saved agy sessions resume with --conversation <ID> and retain the exact full transcript path.