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 stated goal is never a finished product. It 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 strategy and before flow, in the cycle default, implement, strategy, apollo, flow, sovereign, autopilot, 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.
  • 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.
  • Interactive only: The interview needs a terminal interface. The headless control surface refuses a permission-mode change to apollo in SDK and print mode.
  • Main agent only: The Apollo instructions join the system prompt only while the live mode is apollo, and they drive the main agent only. Sub-agents never receive them.
  • Mode switch: A mid-session switch into Apollo takes effect at the next turn's prompt build.

Enter Apollo mode

To enter Apollo mode, follow these steps:

  1. 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; authoring an "Other" option is forbidden.
  • 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 and never pads to the budget.
  • 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, never guessed.

The letter E keeps its identity even when fewer than four options were authored. The letters are display only: answers, drafts and re-asked questions never carry a letter.

Review the specification

To review the specification, follow these steps:

  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

With no blockers, the card asks whether to begin the prototype build and offers three answers. Both yes answers complete the mode transition out of Apollo and differ in permission breadth only.

  • Yes, begin the build: Moves the session to the build posture, flow when the classifier gate allows it and implement otherwise. Edit consent rides the mode.
  • Yes, but ask before each edit: Moves the session to default. The build runs and each edit asks for confirmation.
  • No, ask more questions: Nothing moves. The session and drafts are preserved, and the agent resumes the interview and presents the review afresh.
  • Esc: A plain rejection. The agent waits for your word.

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

Prototype build

On a clean, approved review the tool moves the session through the same guarded transition the carousel uses, so entering flow arms the classifier and strips dangerous rules exactly like a Shift+Tab entry. If flow became unavailable between the check and the set, the tool falls through to implement, which is always available, so an approved review never leaves the session stranded in Apollo Mode. The output records whether the build started and the settled mode, or that the interview continues.

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