Mercury CLI
Documentation

Start

Apollo mode

Apollo Mode is a session permission mode in which the agent interviews you until the missing specification exists, writes that specification down, and then builds a prototype from it in one autonomous run.

The goal is a one-shot prototype: for a game, a playable demo with UI and example animations; for other software, the equivalent runnable slice, enough to decide whether the idea is worth continuing.

Mode behavior

  • Carousel position: apollo joins the Shift+Tab carousel directly after implement and before flow, in the cycle default, implement, apollo, flow, sovereign, default. From apollo the carousel lands on flow when the live flow gate allows it, else on sovereign when bypass is available, else on default. Sovereign is available in every interactive session unless settings or policy disable it; mercury run requires --sovereign or --allow-sovereign.
  • Presentation: The band shows the title Apollo Mode with the seal ◇ and its own tint.
  • Permission posture: Externally the mode projects as default. Apollo is never a bypass posture.
  • Where it works: In the terminal and in an ACP editor, which answers the interview through form elicitation. mercury run has no Apollo Mode, because it cannot answer an interview.
  • Main agent only: The Apollo instructions join the system prompt only while the live mode is apollo, and they drive the main agent only.
  • Mode switch: A mid-session switch into Apollo takes effect at the next turn's prompt build.

Enter Apollo mode

Press Shift+Tab in an interactive session until the band shows Apollo Mode. The main agent receives Apollo's interview instructions on its next prompt build.

Interview and specification

The agent interviews with the AskUserQuestion tool. During this phase it writes and edits only the specification files.

  • Poll choices: Every poll is multiple choice with exactly four authored options. Mercury letters them A to D and adds E automatically as the free-text answer.
  • Question grouping: One question per poll by default. Up to four questions batch in one call only when they are independent.
  • Question wording: Questions are plain language, each tied to the technical choice it settles.
  • Question budget: The apollo.preflightQuestions setting, default 7. The agent uses fewer when nothing blocks.
  • Specification directory: <project>/.mercury/apollo/ holds the completed specification as readable files.
  • Remaining blockers: Whatever still blocks after the budget is named in the specification.

The letter E keeps its identity even when fewer than four options were authored. The letters are display only.

Review the specification

To review the specification:

  1. Read the plain-language summary on the review card the ApolloReview call renders.
  2. Inspect the listed specification files and blockers.
  3. Choose a review answer.

Mercury moves the session to the chosen build posture, or keeps it in Apollo Mode for more questions.

The agent calls ApolloReview with the summary, the blocker list, the specification file paths and a run note. The call is refused outside a main-session Apollo interview.

Review answers

When there are no blockers, the card asks whether to begin the prototype build and lists three answers. Both Yes answers leave Apollo Mode. They differ only in which edits require permission.

  • Yes, begin the build: Moves the session to the build posture, flow when it is available and implement otherwise. Edit consent follows the mode.
  • Yes, but ask me before each edit: Moves the session to default. The build runs and each edit asks for confirmation.
  • No, ask me more questions: Keeps the session and drafts in Apollo Mode (with an optional note on what still needs asking), and resumes the interview.
  • Esc: A plain rejection. The agent waits for your word.

With blockers present, the call is informational: the card presents the blockers. The agent resolves them with you, then reviews again.

Prototype build

After an approved review with no blockers, Mercury changes mode through the same checks used by the permission-mode carousel. Entering flow sets dangerous allow rules aside, just as Shift+Tab does; if flow is unavailable, Mercury selects implement. An approved review therefore ends Apollo Mode for the session and records buildStarted with the settled mode (or interviewContinues when you asked for more questions).

The agent then builds the prototype in one autonomous run with the completed specification as the brief, and finishes by stating in plain terms what was built and how to run it.

Permission modes · Workspace trust and permissions · Sessions