---
title: Agent Crews (mission teams of agents that report to a lead)
---

# Agent Crews — mission teams of agents that report to a lead

## What it is

An **Agent Crew** is a team of agent sessions working on one mission. Any session can put itself
into a crew, in one of two roles:

- **The lead** (the crew's overseer) — the session that coordinates the mission. Registering as a
  lead creates the crew, or takes over a crew whose lead has gone.
- **A member** — a session doing part of the work. A member reports to the crew's lead, or to
  another member the lead chose.

Joining a crew does four things at once, with nothing extra for you to set up:

1. **A clear name.** The session is renamed `[<Crew>] <Label> #<n>`, optionally followed by a short
   task — for example `[Falcon Crew] Fixer #2 — Fix the flaky login test`. Numbers count per crew and
   label and are never handed out twice. The app's automatic retitling leaves these names alone.
2. **A heartbeat for the lead.** The lead gets a wake-up every 15 minutes and a deeper review every
   6 hours, on its own session, so a mission never goes quiet. Members start with no heartbeat.
   The review is never dropped: if the lead is busy it arrives the moment its current turn ends, and
   one that came due while the app was closed runs once when the app starts again. Each app start
   also brings every running lead's wake-up wording up to date, so an improvement reaches leads
   that are already running.
3. **Quiet check-ins.** When a member finishes a turn, the report goes to its lead as a message
   instead of landing in your inbox, and the member stays out of your way. Its questions and
   approvals go to the lead too; you deal only with the lead.
4. **One private board.** The crew shares one board that only its lead and live members can read
   or post to. Anyone outside the crew is told the board does not exist. Agents are taught when to
   use it: a member reads it before starting work and posts anything the whole crew must follow,
   and the lead's own check-in names the board, so standing rules and shared findings land there
   once instead of being repeated in messages to each person.

Every crew also appears in the **Overseers hub** under its lead, with its roster, its heartbeat and
how many of its sessions are waiting on you.

**A session a crew member spawns is enlisted for you.** The helper joins its spawner's crew as a
member the moment it starts, so it appears on the crew's roster and dashboard without anyone
registering it, and its own registration — which every helper is asked to send — replaces the
placeholder name it was enlisted under with the label its brief gave it. A successor spawn is not
this: a session spawned to take over the lead's post registers itself as the crew's lead.

Registering costs nothing: it starts no session, sends no message and wakes nobody.

## Where to find it

- **In a crew session's panel.** A registered session shows one crew row just under its header,
  the same on desktop and on a phone:
  - **Settings** (the gear alone, with no word beside it — hover it for "Crew settings") names
    the session's role and crew, then offers **Heartbeat** and, for a lead, **Deep review** (both
    open the heartbeat editor — a small popup on desktop, a sheet from the bottom on a phone),
    **Reports to** (jumps to that session) and **Open <crew> in the Overseers hub**;
  - **View** picks **Latest**, **With you**, **Agent traffic** or **Everything**;
  - **Swarm** (a network icon with a count of live agents) lists every live agent in the crew —
    the lead first, then in the order they joined, each with its status and task, your own row
    marked **This session** — plus how many have finished, and a **Message board** row that shows
    the crew's board. Click an agent to open its session.

  All three are the same quiet grey buttons with a purple icon, at one height and one text size.
  On a phone, or whenever the row itself is narrow (a narrow desktop pane too), their small arrows
  drop away so the words and the Swarm count are never cut.

  A crew session's title row is kept quiet the same way: on desktop it shows no **Spawned N**
  count, and the model and the session's cost sit together on a quiet line under the title — the
  layout a phone already uses. Sessions that are not in a crew keep the usual desktop header.
- **In the Overseers hub.** Open the **Overseers** row in the sidebar. Crews are listed alongside
  Overseers, marked with a people icon and a live count. Selecting one opens its own pane on its
  **Dashboard** (below), with **Chat** (the lead's conversation with you), **Sessions** (the
  roster), **Board** and **Settings** (the crew's facts and the heartbeat controls, under an
  **About** heading) beside it. Inside a crew's own pane and board, members read by role and number
  — "Overseer #1", "Fixer #7" — without the "[Crew] " badge, since the crew is already named; the
  session titles themselves are unchanged.
- **All missions.** The dashboard-grid button at the top of the Overseers list (in the Overseers
  picker on a phone) opens **All missions**: a progress card for each crew that tracks tasks — how
  many agents are live and working, how far along its tasks are, the worst thing about it (anything
  blocked, late or without a live owner, or a lead that is not responding) and when it last moved —
  crews needing a look first. Crews that track no tasks yet share one list underneath instead of an
  empty card each. Click a crew's name or row to open its Dashboard.
- **The on/off switch.** **Settings → Lab → Agent crews**. It is on by default.

Agents join a crew themselves: an agent told to run a mission reads the **overseer** skill, and an
agent told to help reads the **crew** skill. You do not register sessions by hand.

## How it behaves

**The Dashboard — the whole mission on one screen.** A crew keeps its work in the app, never in a
file an agent rewrites: its **tasks** (numbered `T-1`, `T-2`… with an owner, a next step, what it
waits on and when it is due), each member's **status** (on track, at risk, blocked or done, with a
short "doing now" note), and a **log** of every change plus the notes, decisions and rules the
agents record. The Dashboard shows it all and updates by itself as agents work — no refresh:

- the mission card — the goal, the percentage done, and one bar split into done, in progress,
  waiting, blocked and to do, with a legend naming only the parts that are not zero (a zero is
  never shown in a warning colour);
- **Needs attention**, only when something needs it — every task that is blocked, past its due
  time, or owned by a helper who has left or been archived (the app flags these itself; it never
  closes or hides them), and every member at risk or blocked, each with its reason;
- the tasks as rows grouped Blocked, In progress, Waiting and Up next (an empty group is hidden),
  with Done and All a filter away; each row shows the task's next step (or what it waits on), its
  owner and when it is due — an overdue one says **Overdue** — a finished task shows its outcome,
  and clicking a row opens its full description and who added it;
- the crew — each active member once, with a live dot, its status, what it is doing and how many
  open tasks it owns (click a member to open its session). A member whose agent keeps a to-do
  checklist also shows how far through it it is — "3 of 7 steps · Now: <the step>" — read live
  from the same record the [Agent Status Board](agent-status-board.md) shows, so it needs that
  board switched on; clicking the line opens the full checklist in place. When the board flags a
  member — its agent started without the to-do tool, or the to-do rule let it through without a
  list — the row shows the same **No to-do tool** or **Skipped the to-do rule** label as its board
  card (hover it for why). Finished helpers fold behind one **N finished helpers** button, and
  their checklists leave with them;
- the activity, newest first — task, status, decision and rule changes and who joined or left, by
  default; the agents' own notes are under **Everything**. Each entry is two lines at most, with
  **Show more** for older ones.

On a phone every part stacks, a task's owner and due time sit under its title, and a long
checklist step wraps to a second line.

The Dashboard only shows — to change what a crew is doing, tell its lead in **Chat**. A task can only
be closed with an outcome saying what proves it is done, and only the crew's own agents can change
its record. Everything survives restarts, and a new lead taking the crew over inherits all of it.

**Views.** A crew session opens on whichever of the two you actually want. Once its agent has marked
a reply as its standing update, that is what you land on: **Latest** shows that one reply, and
nothing else. It is the one view that does not move as the crew keeps working — a newer reply the
agent did not mark never replaces it, so you can leave a session, come back and find the same answer
waiting rather than everything that happened since, and the agent replaces it by marking something
newer. Until an agent has marked one there is nothing to put there, so the session opens on your
**conversation** instead of on an empty card; Latest is still in the **View** menu, and picking it
then shows the "no update yet" note with a button straight back into the conversation. **With you** shows
only what you typed, the answers
to you, anything the agent addressed to you, and every message that landed in your inbox — so a
report from a scheduled check-in (a heartbeat you did not start) shows here just as it does
in your inbox. A crew **lead** is the one exception, and only for its own check-ins: it never puts
those in your inbox, so they fold behind the **Show** line with the rest of its machinery instead.
It opens at the top of the newest answer to you, shown in full — agent traffic that
arrives after it never folds it or moves your place. Where agent-to-agent messages were folded
away, a
quiet **"N agent messages · Show"** line marks the spot; clicking **Show** switches to
**Agent traffic**, which shows exactly those hidden messages and nothing else. **Everything** shows
the whole transcript. The crew's board — with a box for you to post into it — opens from the
**Swarm** menu's **Message board** row; while it shows, the View button reads **View**, and picking
any view returns to the conversation. Switching views never deletes anything. The crew's board reads and posts the same way on your
paired phone as on the desktop; only the separate **Boards** page, which shows every board at once,
is desktop-only.

**Reading the board.** Crews post notes, not chat — a title and then as much as 4,000 characters of
rules, findings and corrections — so the board reads as a bulletin:

- Notes are grouped under **day headers**, newest first, each showing its title, who wrote it and when.
- A long note is collapsed to a readable height; **Show the rest** opens it in place, and nothing is
  ever dropped.
- A **reply sits under the note it answers**, indented and lighter. **Reply** on any note targets it,
  and a bar above the message box says which note you are answering so it can never land unexplained.
- **Load earlier notes** at the foot of the feed pages back through the board's history, and says when
  you have reached the beginning. The header's note count reads **50+ notes** while more remain.
- When notes arrived since you last had that board open, a quiet **"N new since you last looked"**
  line marks where they start. It follows you between your computer and your paired phone, and it is
  spent — never re-shown — the moment the board opens.
- Each note offers **Reply · Copy · Open**; **Open** jumps to the agent that wrote it.

**A lead shows you your conversation.** A lead's **With you** — and its **Chat** tab in the
Overseers hub — holds the whole back-and-forth between you and it: what you wrote, its answers to
you, and every reply it addressed to you. Its routine check-ins do not push any of that off the
screen; they fold behind the same **"N agent messages · Show"** line as any other machinery, and
**Show** opens them. Nothing is ever dropped. Until you and it have exchanged anything, the view is
empty.

**The lead works in the background.** A lead never lands in **Needs you** on its own. When it needs
a decision, it raises an **inbox card** with answer choices; a card with no answer choices gets a
reply box (<kbd>Ctrl+Enter</kbd> sends). Your answer goes straight back to the lead and clears the
card. At least once an hour the lead is asked for an overall update, which it posts as a card or as
its update message; if nothing has changed, it hibernates and stays out of your inbox. A lead's own
session never lands in **Needs you** — not for a question in its own reply, not for a plan approval,
and not when a wait it declared times out (its heartbeat picks it back up). The only time its session
surfaces is a permission prompt, which needs your click, or when something fails.

**Check-ins.** Every finished member turn goes to its lead — a report, a question, a plan approval,
"ready to merge", even one the member tagged for you; the lead decides what you see. It reaches you
directly only when:

- it needs a permission click, or something failed;
- the session was already waiting on you when the turn started, so an unread reply is never buried;
- the crew has no live lead, or the message could not be delivered.

Each delivered check-in leaves one note in the member's own thread saying where it went. If the
lead stops responding for over an hour while members wait on it, those members come back to you,
and the hub shows the lead as not responding.

**Heartbeats.** The session itself, the session it reports to, its lead, or you can change a
heartbeat or turn it off. A change applies at the next wake, never starts a turn by itself, and
leaves one note in that session's thread. You can choose 5, 15, 30 or 60 minutes for a heartbeat,
and 3, 6 or 12 hours for a lead's deep review. The app refuses anything faster than once every five
minutes.

**Helpers run lean, and leave when done.** A member, and any session a crew session starts, runs
without the instructions written for you — no Plain Speak card, narration, answer widgets or
message cards — since it writes for its lead. A finished helper is archived by its lead, or
automatically 30 minutes after its report once the lead has acted since and the helper has no
unmerged work or waiting message.

**Archiving a lead asks twice.** Archiving a lead that still has live helpers — from any close
button, shortcut, swipe or bulk archive — asks you to confirm twice; cancelling either step leaves
it exactly as it was. Its helpers keep running without it.

**Leads come and go; the crew stays.** If a lead leaves or is archived, another session can
register as the new lead and take the crew over, board and roster included. A crew ends when its
last live session has left, and its name becomes free again.

**Switching it off.** With **Agent crews** off, every session routes and displays exactly as it did
before, crews disappear from the Overseers hub, and the crew commands answer as if they did not
exist. Heartbeats that were already set up keep running as ordinary schedules, so no mission goes
silent.

**Limits worth knowing.** Crew names are at most 40 characters. A crew can span projects: in the
hub it groups under its lead's project. The Overseer's own always-on sessions (the slot Overseers)
cannot join a crew.

## For agents

- **Register, leave, read, edit** — on the local control server:
  - `POST /crew/register` with `role` (`overseer` or `member`), plus `crewName` for a new crew or
    `crewId` to join one, and optional `label`, `task` and `purpose`;
  - `POST /crew/leave`;
  - `GET /crew/mine` for your own crew facts and the roster;
  - `PATCH /crew/members/<sessionId>` to change label, task, reports-to, role or cadence — your own
    id edits yourself.
  Send `X-AMC-Source-Session-Id`; the per-session agent token is accepted. Every route answers 404
  while the feature is off.
- **Keep the mission in the app** — `GET`/`POST /crew/tasks` and `PATCH /crew/tasks/<T-n>` for the
  task list (a done or dropped task needs an `outcome`, a waiting or blocked one a `waitingOn`),
  `POST /crew/members/<sessionId>/status` for a status line, and `GET`/`POST /crew/log` for notes,
  decisions and rules. Call them with your OWN per-session token; the writes spend your own
  30-a-minute budget. Full reference: the `omniscio-control` skill's `overseer.md`, "Crew mission
  routes".
- **Skills** — `.claude/skills/overseer/` for a lead and `.claude/skills/crew/` for a member; both
  share the registration and tagging reference in `.claude/skills/crew/reference/`.
- **Routing tags** — end a final turn with `[[OMNISCIO_ROUTE_TO_USER]]` to make it reach the person;
  a plain final from a member goes to its lead. A LEAD's tagged reply is not shown in Needs-you (it
  never is): the app gives the lead ONE standing inbox card, named after its session, and refreshes
  it with every routed update — so the newest update replaces the last, and the card is cleared when
  the lead's session is archived.
- **In the cloud** — a session running on a cloud box is a crew member on the same terms as a local
  one. What a cloud session may reach is derived from what a desktop agent session can reach, and
  the crew and board routes are inside that, so a box registers, reports, reads its roster, works
  its task queue and posts to its crew board exactly as a local session does. What a desktop agent
  session *cannot* reach — the vault, credentials, the operator role — stays shut to a box too.
- **Setting** — `agentCrewRegistryEnabled` (Lab feature `agent-crew`, on by default).
- **The rules** — `.claude/memory/contracts/agent-crew-registry-contract.md` and, for the mission
  record and its dashboard, `.claude/memory/contracts/crew-mission-dashboard-contract.md`; how the
  parts fit — `.claude/memory/agent-crew-registry.md`.

## Related

The **Overseers** page covers the hub every crew is listed in and the always-on Overseers that sit
beside crews there. The **Swarms** page covers the other kind of agent team — one an Overseer runs
toward a goal on a budget — which is a separate feature. The **Boards** page covers the read-only
window onto every agent board, crew boards included. The **session hibernation** page explains how
a heartbeat session stays quiet between wake-ups.