Mercury CLI
Documentation

Input

Computer use

Computer use is the Computer tool. The model takes a screenshot, acts in the application in front, and sees a fresh screenshot after every act. Nothing runs without consent: the first act in each application asks by the application's name. The tool is on by default on a machine that has the desktop driver, and the rest of Mercury does not depend on it.

Access types

The Boot Menu's Computer use row carries an Access type row with three values.

  • asks: The default with Sovereign mode off. The first act in each application asks, and a Yes covers that application for the session.
  • permissive: Takes the application in front at the turn's first Computer call as the turn's home application. Acts in it never ask; an act in any other application asks once. A home application leaves no grant behind.
  • full: Never asks.

Unset, the access type follows Sovereign mode: full with the Sovereign mode row on and asks with it off. A saved value wins either way. MERCURY_COMPUTER_ACCESS=asks, =permissive or =full sets it for one session; any other value is refused.

Reads never ask. Under asks, the first act in each application asks by the application's name and identity, names the act, and asks how long to allow. The five answers, in this order, are:

  • Yes: Allows this act and every later act in this application for the rest of the session.
  • No, and tell Mercury what to do differently: Refuses the act and hands the composer back to you.
  • Yes, for 1 hour, every application: Allows every act in every application for one hour.
  • Yes, for 24 hours, every application: Allows every act in every application for twenty-four hours.
  • Enable sovereign mode to avoid further permissions by default: Turns Sovereign mode on for this session and saves the Boot Menu's Sovereign mode row for later sessions.

With Sovereign mode already on, the card offers the first four answers only. A timed grant lives with the session, is never written into settings, and leaves no per-application grant behind. An application that moved in front between the ask and the act is not driven; the model takes a new screenshot instead.

Stop computer use

To stop computer use, follow these steps:

  1. Give keyboard focus to the terminal running Mercury.
  2. Press Esc or Ctrl+C.

Mercury ends the act in flight, releases every key and button the model was holding, and ends the turn.

The stop key reaches Mercury only while its terminal has keyboard focus. Your own mouse and keyboard keep working while a turn drives.

Disable computer use for new sessions

To disable computer use for new sessions, follow these steps:

  1. Turn the Boot Menu's Computer use row off.
  2. Start a new session.

The new session's catalogue omits the Computer tool and touches no desktop driver.

MERCURY_COMPUTER_USE=0 in the environment before the session starts does the same. A running session keeps the tool list it started with until the next compaction or /clear. On a machine without the desktop driver the tool is absent as well.

Application rules

  • Computer(app:<identity>): A rule in permissions.allow grants an application beyond the session. You write the rule; the card writes none.
  • permissions.deny: Refuses the matching application before any ask, in every mode.
  • permissions.ask: Asks for the application in every mode that asks and stands down under Sovereign mode.
  • Application identity: A bundle identifier on macOS such as com.apple.Safari, an executable name on Windows such as chrome.exe, or a window class on Linux such as firefox.

The model never types into the terminal running Mercury: with that terminal in front, only an application-switch key chord is allowed. One session drives the desktop at a time, and a second session that tries to act is refused naming the first.

Screenshots and retained state

Every screenshot is written to <config-home>/desktop-shots/, the newest 200 kept, and sent to the model at the image budget of its route. The conversation file carries only a line naming the file, and after a compaction or a resume the model takes a new screenshot before acting.

Platform requirements

  • macOS: The terminal application needs the Screen Recording and Accessibility grants under Privacy & Security in System Settings. The first capture or act registers the terminal in both lists; restart the terminal application after allowing.
  • Windows: An interactive, unlocked desktop session. Windows drops input into a window that runs elevated when Mercury does not.
  • Linux: An X11 session with DISPLAY set. A Wayland session is refused by name.

The tool needs a model that receives images; a text-only route refuses and names itself. Sub-agents, teammates and MCP serve clients never carry the tool, and a headless run without an approval channel cannot drive. mercury doctor and /health carry a Computer use row naming the driver, the grants, the access type and the session driving the desktop; a missing grant is information, never a fault.

Permission modes, Workspace trust and permissions, Health check, Sessions