Crew
Crewmates are the agents Mercury launches through the Crewmate tool to work beside the session. Each session tracks its own crew. You can follow their work in the Crew view and address them by name or id.
Views and boards
/crewmates: Opens the Crew view with the focused session’s crewmates, one row each. Rows show each crewmate’s name, model, status, tokens in and out with cache reads counted apart, and elapsed time. A crewmate appears from the moment it is launched, before its first reply. A crewmate parked on a permission ask says what the ask is for and when the ask refuses itself, besidewaiting for your answer./runs: Opens the runs board for running shells and crewmates, with detail cards./tasksopens the same board./crew: Opens the crew directory with identities, roles, presence, external connections and why a parked crewmate is waiting (the post it waits for, or a worktree that is missing)./agents: Opens the Agent Studio for building and tuning role definitions./sessions: Manages the project’s sessions.
In the Crew view and in the activity screen (Ctrl+T or the bottom work strip), Enter (↵) opens the selected crewmate in its own view in every layout and terminal size, including /zen and narrow windows (at 80×16, /crewmates states how many crewmates cannot fit and which row Enter opens). While /crewmates is open, the mouse wheel and PageUp/PageDown scroll the crewmates list while the chat behind it stays still, a click selects a row, and a second click on the selected row or a double click opens it just as Enter does. In /zen and the compact layouts, opening a crewmate switches the compact identity band to that crewmate’s card (showing its name, state, elapsed time and the way back), routes the composer to that crewmate, and places a Mercury Lead row at the top of the activity screen’s crewmates list: Enter on Mercury Lead returns to the lead’s chat and m hands the main chat back. In the Crew view, m makes a crewmate’s chat the main one and c clears a settled row. Esc or a click on the chat outside the Crew view closes it. From an open row, either returns to the list first. Closing a view leaves its work running.
Start a crewmate
A crewmate starts through the Crewmate tool, with a name or without one. While it runs, SendMessage delivers it a note, and ResumeCrewmate gives it more work, running or finished, by its name or by the id in its launch receipt. An unnamed one works its prompt once and returns its report, and is reached afterwards by that id. A refused crewmate launch paints as the refusal rather than a finished crewmate, and the turn summary counts only launches that happened.
The crewmate runs on the model the launch names, or on the crewmate default chosen in /config. When a Crewmate call names the parent’s own model family, the crewmate keeps the parent’s exact model; a different family keeps that family’s preferred model, and an exact model id keeps its explicit choice. The launch receipt names the crewmate’s engine and model on every provider, the Anthropic route included. A resume keeps that model and effort unless ResumeCrewmate passes an explicit model or effort override for the resumed turn. Each crewmate’s shell starts in the crewmate’s own folder on every call regardless of cd commands in the parent or sibling crewmates, and a crewmate type denied by permissions.deny remains listed in the Crewmate tool description with its refusal rule and reason.
The Crewmate tool’s cwd names an existing absolute folder. The crewmate’s shell and file tools start there, and that folder is its own starting folder. Starting outside the session’s starting folder asks for ordinary permission; approving launches the crewmate there, and declining leaves it unlaunched. Sovereign mode launches without asking. A missing folder is refused before launch. With isolation: "worktree", the worktree starts at that folder’s checked-out commit, and nothing is fetched. worktree_at can instead pin a specific commit. Each crewmate gets its own worktree; simultaneous launches create them one at a time to avoid a repository-lock collision. The worktree starts with the checkout’s node_modules and each vendored pack the checkout ignores, so the crewmate builds and runs checks there without an install. On a filesystem that can clone (APFS on macOS, a Linux filesystem with reflinks) each is the worktree’s own copy, sharing disk space until one side writes, so what a crewmate installs or builds there reaches neither the checkout nor another crewmate; elsewhere, and for a directory named in workspace.worktree.symlinkDirectories, each is a link to the checkout’s copy. On such a filesystem the worktree also starts with everything else the checkout holds that git ignores (build output, caches, generated files, .env files), each its own copy; build output comes from the checkout as it stood while the worktree holds the commit. Four things stay behind: Mercury’s own folders and instruction files, a folder that holds a pyvenv.cfg or a CMakeCache.txt, a folder that is another git worktree, and whatever a Read deny rule matches. A worktree frozen with worktree_at, cut at another commit than the checkout’s, made sparse by workspace.worktree.sparsePaths, or made in a repository that holds your home directory starts with the dependency folders only. A crewmate starts at once and its first tool call waits for its copy, which takes about a second for every hundred thousand files of what git ignores on a Mac and one to four on Linux. MERCURY_WORKTREE_CLONE=off in the environment keeps the links.
A continued crewmate returns to the folder where it started. If that folder no longer exists, it runs in the session’s folder and the receipt names both the missing folder and the fallback. Each crewmate has its own folder for temporary files.
A crewmate’s end releases its worktree lock and leaves its worktrees and folders in place, with the path and branch returned in the tool result and listed in the session’s reminder, so you can inspect it or remove a clean leftover directly with git worktree remove <path> (Mercury’s seven-day worktree sweep removes only clean, reachable leftover worktrees). A read-only crewmate (mercury-scout) inside a linked worktree can also run read-only git commands such as git status and git ls-files.
Read and message a crewmate
Open a crewmate from its rail row to read its transcript in the chat. Press m to target the composer to it. The hints name who receives the next line, and the model chip shows that crewmate’s model and effort. A sent line leaves the composer immediately and returns if refused. A line beginning with ! runs in the shell even when a crewmate is targeted. Rows you opened stay open across a switch between the main chat and a crewmate view.
With a crewmate opened in its view (or, when none is opened, with one pinned as the main chat), the slash commands that are about one agent act on that crewmate, and the status row says commands → <name>: /model and /effort show and change its model and effort (a running crewmate switches at its next turn, and a finished one at its next resume, while the status row’s chip keeps the running model and effort and appends → <model> · <effort> next turn while a change waits), /compact compacts its transcript at its next turn or when it resumes, /context and /usage show its numbers, and the model-picker key and the command palette’s model row open that crewmate’s picker too (the thinking key changes nothing there: a crewmate’s thinking stays as it was spawned, /effort sets its effort, and the key belongs to the main chat). The main chat’s model, effort, thinking and transcript stay as they were, and every other command (/help, /crewmates, /config, /exit and the rest) runs for the whole session and says so. Selecting Mercury Lead in the rail returns the commands to the main chat; Esc interrupts a running crewmate and returns from an idle one.
The CREW box keeps the session’s running, finished, stopped and interrupted entries. Finished entries are greyed; c clears them. Esc on a crewmate that is not running returns to the main chat.
Messages
SendMessage delivers a note to a running crewmate. It reads the note at its next tool boundary or at the end of its turn. A background crewmate can address main to reach the session that launched it; a message to the main session between turns starts a turn. A crewmate that has finished is not started by SendMessage; the refusal names ResumeCrewmate.
ResumeCrewmate continues a completed, stopped or failed crewmate from its saved transcript (earlier transcripts using ResumeAgent continue to open and resume). If it is still running, the message reaches that run without starting another. A crewmate settles as completed only when its turn ends with an empty message queue, so a message queued while it worked starts its next turn in the same crewmate before the completion notice reaches the main session. When a stopped crewmate is resumed, consecutive user records are merged on the Anthropic wire while resume text stays separate from tool results. A resumed crewmate keeps its model and the output schema its launch named. The main session receives the completion notice, stamped with the time the crewmate finished; a notice that lands a minute or more later also says when it was delivered. If several launches share a name, both tools address the newest.
Live crew board
Swarm is on for new sessions when swarm.enabled in your user settings.json (the Swarm row in /config) is on; the master defaults to on, and false turns it off. /swarm off turns it off for this session's future launches while existing board crewmates keep their board; /swarm on turns it back on. /swarm status shows the switch. Resumed sessions keep their choice. Headless and SDK sessions follow the same default. The board file opens only when a crewmate launches, a board command runs or chat first paints.
Swarm is a high-cost option: sharing board messages costs context, and the Swarm row in /config turns it off.
A crewmate launched or resumed with swarm on is told, in its system prompt, its name, its team, the seats already on the board, and when to post and read; the lead's brief adds the task's own habits, and a crewmate re-entering keeps the crew-board brief it was first given so its cached system prompt stays intact. SendMessage and ResumeCrewmate from the lead, and SendMessage back to main, stay direct and whole whether swarm is on or off. The board keeps only the first 400 characters plus … (sent directly) for the timeline. That mirror is not delivered to the model.
With the board on, /swarm opens Crew chat in the Workbench. It combines board posts and crew traffic in one live timeline, with each author's name, time, team and kind. Mirrored messages carry a traffic tag. Replies sit under their ask. A message wraps to three lines in the timeline; the thread holds the whole text. ↑↓ moves, ↵ opens a thread, ←→ selects General or a team, and esc closes. The view is read-only, with no composer, and is absent when the board is off.
With swarm on, board messages show in the chat. Each message is its own row with its time and author; each crewmate has its own colour, the same in the Workbench. A crewmate joining (joined · team <team>) or parking (parked · waiting on <event>) shows as a row too; a crewmate finishing shows as its completion notice. Messages wait for the lead's current block to finish and stay where they land; the turn summary under the lead's reply counts tool work only. When the conversation compacts (/compact or auto-compaction), board rows from the compacted turns compact with them instead of repainting after the summary.
The channel is on by default, with nothing shown until the crew is active. /swarm on also shows the wave's launch line. /swarmchat alone toggles it for this session; /swarmchat on and /swarmchat off set it explicitly without changing the selected filter. Choose /swarmchat all, /swarmchat team <name> or /swarmchat main to select new messages; main shows posts addressed directly to the lead. The Workbench keeps the full board.
CrewBoard posts questions, answers, blockers and results. A result or blocker may include about with a description, path or URL; it needs neither a task id nor an evidence reference. @seat, @team and @all in the text or the optional to list address enrolled members. A post addressed only to unknown names, with no team delivery or @main, is refused with the instruction to launch seats through Crewmate. A post with a real addressee still lands and reports unknown names in its receipt. Every post reaches every enrolled crewmate whole, with its about and thread, at that crewmate's next boundary; an ask or blocker addressed to the lead with @main or @all, and a result, answer or correction addressed to @main by name, wake an idle lead, batching waiting posts into one turn.
The lead can give a Crewmate launch a team label or assign one later with CrewBoard's swarm_team operation (seat and team), and name a team's captain with captain: true on the launch or with swarm_captain (team and seat). Teams are labels for delivery and channels. There are no private messages: everyone can read every post. A read without a team selects the general timeline.
The lead names a captain for a team of five or more crewmates. A smaller team has one when you ask, or when a crewmate asks and the lead agrees. Captains gather their team's work and report it to the lead.
On the board one name belongs to one crewmate. A launch that takes a name takes it from a parked crewmate that carries it: the parked crewmate leaves the board with its own wait, and the waits other crewmates declared on it and its captaincy pass to the new one. While the crewmate that carries the name is running, the launch is refused. A crewmate that left the board this way and is resumed by its id takes the name back by the same rule. A launch that names nobody takes no name. main and all are the board's own addresses: no crewmate is launched under either.
/general <text> posts to every crewmate. /team <name> <text> posts to that team's captain, or all its members when it has none. /whisper <name> <text> posts to one crewmate. Names complete as you type. Your posts carry your own label and colour and reach the lead too. Every board post remains readable by the crew. Ordinary prompts go only to the lead.
Crewmates can park with a declared wait for another crewmate's post, a file or subject, a message kind, or their team's traffic. A matching message or a post addressed to them can resume their conversation. Broadcasts do not resume parked crewmates. The status shows what each waiting crewmate needs. If its worktree is unavailable, it stays parked and the lead receives the path.
A read without since continues from the seat's cursor, starting at its enrollment. Whole events already handed to its model, through a read or a boundary message, are skipped. The receipt counts those seen events and names the re-read road: since: 0 or since: <seq> deliberately reads them again. Reads return every new event oldest-first.
A correction names an earlier event id in corrects and appends the replacement words beside the original in its thread. The earlier post stays readable and links to its correction.
File leases
The in-process mercury MCP server that every session carries holds project file and directory leases: mcp__mercury__lease_take takes the named repo-relative paths for the calling session and crewmate (a file, or a directory with a trailing slash such as art/, which is one lease covering everything under it), mcp__mercury__lease_release releases the named paths or every lease the caller holds when paths is omitted or null, and mcp__mercury__lease_list answers with one row per holder (session, crewmate, count and the directory its leases share), with the leases themselves while there are at most 100, or those of the crewmate named with agentId. The session director (main) can pass agentId to release that crewmate’s leases, or all: true for every holder in its own session, never another session’s. A path another live holder has taken, or a file under a directory it holds, is named and refused, so you coordinate with that holder; a lease call runs in milliseconds whatever other crewmates hold, and a failing call answers with its reason. A crewmate’s leases are freed when it finishes, fails or is stopped, and a resumed crewmate can take them again. The same server serves render_tui, the terminal capture.
Roles
Two agents are built in. mercury-crew is the default for delegated work of every kind: research, multi-step changes, running and checking commands, or carrying a brief such as a design, a review or a check to its end, with the session’s full tool set in the foreground and the background alike (Eval, Test, Debug, Launch, Service, Monitor, Browser, Journey, Git, Transaction, Structure, AstSearch, AstEdit, ChangeSet, the Lsp family, Inspect, Checkpoint, Rewind, TaskStop for stopping its own background commands, and the rest), except the few tools that require you present or reach past the crewmate’s own work (AskUserQuestion, ApolloReview, AskAdvisor, Computer, Journal, CronCreate, CronDelete, ScheduleWakeup, RecordConvention, and Crewmate itself). Every process a crewmate starts (background shells, Eval kernels, session-scoped services, debug sessions, its browser) ends when the crewmate ends. mercury-scout is the read-only reconnaissance agent: it locates files, searches code and answers how-does-this-work questions with paths, line numbers and excerpts, keeping only the reading forms of tools, and a call that would write or change state is refused. Everything else is your own: an agent definition file adds a kind of agent with its own prompt, tools and model, and /agents opens the Agent Studio to build and tune those definitions. The Crewmate tool’s roster and mercury roster list the two built-ins first, then your own agents. A crewmate’s kind is resolved by the Crewmate tool’s crewmate_type, so a given kind is the same agent however it launches, and a saved crewmate record whose type Mercury does not know resumes as mercury-crew.
Three briefs are available as commands, skills and launch options. /verify sends the session’s work and a brief that asks a crewmate to look for faults directly through the Crewmate tool. It ends with a VERDICT: PASS, FAIL or PARTIAL line. A Crewmate launch with isolation: "worktree", worktree_at and review_receipt reviews a committed change on a frozen worktree, with the receipt’s ## Review section as its one permitted write, and ends with REVIEW: CLEAN or REVIEW: FINDINGS <count>. The mercury-docs skill answers how to use Mercury from the documentation that ships with the install.
Stop and resume
To stop a crewmate:
- Open
/crewmatesor/runs. - Select its row.
- Press
xtwice within two seconds.
The first press names the crewmate; the second stops it. Its row shows the reason and its transcript remains on disk. The same controls stop a background shell. The receipt confirms that the runner stopped, or gives the reason it could not. p parks every crewmate and the chat at its next safe point, after a stream or a tool in flight finishes, and resumes them.
To resume a stopped crewmate, select its row and press r; ResumeCrewmate addressed to its name or id does the same. It continues from its transcript, with its earlier work in context, under the same name and model (or the model and effort override passed to ResumeCrewmate). Sending a message (SendMessage, ResumeCrewmate, or typing in the crewmate’s view) to a crewmate paused with p wakes that crewmate alone while keeping the rest of the crew parked, and typing a prompt into a paused chat opens the pause gate and answers the turn. A background crewmate’s completion report held after Esc wakes the idle session at the nudge deadline, and a stalled crewmate request that has emitted no bytes is retried once at the watchdog deadline before stopping. The lead receives notifications when work is stopped, resumed or fails.
TaskStop is the stop tool. In the main session it accepts a task id, the id in a crewmate’s launch receipt or its launch name; inside a crewmate, TaskStop allows the crewmate to stop only its own background shell command. A background shell command has its own row on /runs; when it finishes, its notification goes to the session or crewmate that launched it. A crewmate with nothing to do until then waits with the Sleep tool, which every crewmate carries: the wait names a ceiling of at most an hour and ends the moment the shells that crewmate launched settle. If a crewmate makes a second consecutive failed call to the same tool with the same canonical JSON arguments (including permission or hook refusals), Mercury warns it with the error text to change its call, and a third consecutive identical failing call ends the crewmate’s turn once the round settles with loop_stopped, naming the tool, the call’s field names and value shapes (never the values) and the error in its completion notice.
Pressing Esc in the main chat stops the main chat’s turn while its crewmates keep running. While the main chat compacts its context, a crewmate’s view shows the crewmate’s own transcript.
Usage limits and provider pauses
A crewmate that reaches a usage limit pauses instead of failing. Its row shows the provider’s reset time, and it resumes at that time or when you sign in on another account, with the same model. A crewmate whose turn ends on a provider’s refusal of an image it was sent continues once by itself: the image goes to it as an [image] note with a line saying so, and a second refusal ends the turn.
A crewmate paused by an overloaded provider stays on the list. Mercury first probes after 30 seconds, then every minute for ten minutes, then every five minutes, for up to one hour. An answering probe resumes the crewmate from its transcript; a message can resume it sooner.
Delegation switches
The Boot Menu’s Agents section sets Crewmates for new sessions. Each session keeps its own setting.
/crewmates onor/crewmates off: Adds or removes theCrewmatetool and allows or refuses launches from that session. Work already running finishes.
A change during a turn applies when that turn ends, before queued input runs. With no turn running, it applies immediately. The receipt says when it takes effect. The Session Concourse can still launch sessions because the switch belongs to the focused session.
The Crewmates while backgrounded row, in /config and in the Boot Menu's Agents section as one switch, is off from the start. With it on, a session left in the background launches crewmates when its brief says so, as a focused one does. With it off, a backgrounded session works alone until you visit it or the crewmates-allowed grant applies, and a refused launch names this setting as the third way to allow it. The receipt reads the row's state back in those words.