Crew

Every Mercury session has a crew from the moment it starts: the crewmates, Mercury’s sub-agents, that it delegates to through the Agent tool. There is no create step and no delete step. The crew is born with the session, its crewmates are tracked live, and a message reaches a crewmate by its id or its name.

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, not after its first reply.
/runs: Opens the runs board for running shells and agents, with detail cards. /tasks opens the same board.
/crew: Opens the crew directory with identities, roles, presence and external connections.
/agents: Opens the Agent Studio for building and tuning role definitions.
/sessions: Manages the project’s sessions.

In the Crew view, Enter opens a crewmate’s row in its own 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 does not stop its work.

Start a crewmate

A crewmate starts through the Agent tool, with a name or without one. A named crewmate takes further instructions through SendMessage addressed to its name, after its first turn and after it has finished. An unnamed one works its prompt once and returns its report, and is reached afterwards by the id in its launch receipt.

The crewmate runs on the model the launch names, or on the crewmate default chosen in /config. When an Agent 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. A resume keeps that model.

The Agent 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 does not ask. A missing folder is refused before launch. With isolation: “worktree”, the worktree starts at that folder’s checked-out commit, not a remote branch, 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 links to the checkout’s node_modules and vendored packs, so the crewmate builds and runs checks there without an install.

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 leaves its worktree in place. Nothing is deleted automatically: the worktrees and folders stay where they are, and the session gets a reminder naming each leftover worktree by its path. What to remove is your decision.

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 lead and a crewmate view.

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 Mercury Lead.

Messages

SendMessage carries a plain message to a crewmate of this session, by the id in its launch receipt or by the name its launch gave it, and from a background crewmate to main, the agent that launched it. A running receiver reads the message at its next tool boundary, otherwise at the end of its turn. A receiver waiting between turns starts a turn for it. A receiver that has finished is resumed from its transcript with the message as its next turn, and the answer names the new row and how the earlier run had ended. A name that two launches carried reaches the newest.

File leases

The in-process mercury MCP server that every session carries holds exact project file leases. mcp__mercury__lease_take takes the named repo-relative paths for the calling session and agent, mcp__mercury__lease_release releases the named paths or every lease the caller holds, and mcp__mercury__lease_list lists the leases with their holders. A path another live holder has taken is named and refused, and a holder’s end frees its leases. A lease denial is coordination, not an error. 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 verification to its end, with the session’s full tool set. 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, 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 Agent tool’s roster and mercury roster list the two built-ins first, then your own agents. A crewmate’s kind is resolved by the Agent tool’s subagent_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 ride as skills and launch options. /verify hands the session’s work to the verifier skill, which red-teams it in a crewmate of its own and ends with a VERDICT: PASS, FAIL or PARTIAL line. An Agent 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 /crewmates or /runs.
Select its row.
Press x twice 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 workflow run. The receipt confirms that the runner stopped, or gives the reason it could not. p parks every agent 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, or send a message to its name or its id. It continues from its transcript, with its earlier work in context, under the same name and model. The lead receives notifications when work is stopped, resumed or fails.

TaskStop is the agent’s stop tool. It accepts a task id, the agent id in a crewmate’s launch receipt or its launch name. A background shell command has its own row on /runs; when it finishes, its notification goes to the agent 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.

Esc on Mercury Lead’s screen stops the lead’s turn while its crewmates and workflows keep running. Pausing a workflow pauses that run’s agents. While the lead compacts its context, a crewmate’s view shows the crewmate’s own transcript, not the lead’s compacting row.

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 carries on 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 helper 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 helper from its transcript; a message can resume it sooner. A workflow that ends with agent failures reports their count, the first failing agent and its cause, with the failure details kept in the run record.

Delegation switches

The Boot Menu’s Agents section sets Crewmates and Workflows for new sessions. Each session keeps its own settings.

/subagents on or /subagents off: Adds or removes the Agent tool and allows or refuses launches from that session. Work already running finishes.
/workflows on or /workflows off: Adds or removes the Workflow tool and allows or refuses workflow launches. The runs board stays readable.
Bare /subagents: Reports both switches and where their values came from. The health check’s Crewmates & workflows row shows the same facts.

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 switches belong to the focused session.

A workflow’s stall watch allows fifteen minutes without progress before resuming an agent from its transcript. Provider pings count as progress. A run belongs to the session’s project, and its agents’ fresh input and output token counts add up to the run’s total.

Sessions, Saturn scheduling, MCPs and skills, Command-line reference