Mercury CLI
Documentation

Extend

Editor bridges

Mercury connects to code editors through the Agent Client Protocol and through its VS Code extension. The Unity, Blender and Godot tools drive a running editor over a token-authenticated loopback connection, and the Aseprite tool runs the application's own batch command line. Each editor tool sits behind its own opt-in switch. In every editor tool, reads never ask permission and every other verb asks.

Code-editor integration

  • mercury acp --stdio: Runs the editor bridge over the Agent Client Protocol.
  • mercury editor <action>: Manages the IDE side of the integration.
  • VS Code extension: Runs Mercury in the editor and attaches a terminal session to it. /ide brings the editor's selection, diagnostics and native diffs into the terminal session.

Install the VS Code extension

To install the VS Code extension, follow these steps:

  1. Run mercury editor install.

Mercury installs its VS Code extension.

Unity tool

The Unity tool drives a running Unity editor through an editor-side C# package that Mercury ships as source and installs on request.

  • MERCURY_UNITY=1: Arms the Boot Menu row named Unity dev lanes. The tool joins the catalogue only inside a Unity project, one with Assets/ and ProjectSettings/ at its root.
  • unity_bridge_install: Writes the embedded package, the project token and, only when the port differs from the default, a port file.
  • play_state, scene_list, hierarchy_read and console_tail: Read editor state.
  • scene_open: Opens a scene in edit mode; unsaved changes refuse with SCENE_DIRTY.
  • play_enter, play_exit and play_pause: Control play mode.
  • tests_run: Starts a Test Runner run, with results as NUnit XML.

Play-mode transitions and script recompiles drop the bridge connection; Mercury reconnects on the next call, and a test run's results file survives the reload.

Blender tool

The Blender tool drives a running Blender through a Python add-on that Mercury ships as source and installs on request. It joins the catalogue only beside a .blend file.

  • MERCURY_BLENDER=1: Arms the Boot Menu row named Blender dev lanes.
  • blender_bridge_install: Writes the add-on source, the token and, only when the port differs from the default, a config.json into one directory under the add-on home; with no Blender located and no directory pin, it refuses and writes nothing.
  • blender_status: Reports installation and connection facts; an answering bridge proves that Blender is open with the add-on enabled.
  • scene_info, objects_list, render_state and report_tail: Read Blender state.
  • blend_open: Opens a .blend file inside the working tree; unsaved work refuses with BLEND_DIRTY.
  • render_still: Renders a frame as an editor job; the image file is the durable result. During a render, other verbs refuse with RENDER_ACTIVE.
  • python_run: Runs Python inside Blender with full bpy authority; the ask carries the code's byte count and first line. A running script cannot be preempted or cancelled.

Enable the installed Blender add-on

To enable the installed Blender add-on, follow these steps:

  1. Open Blender's Edit menu.
  2. Open Preferences.
  3. Open Add-ons.
  4. Search for Mercury.
  5. Enable the add-on.

The add-on can then answer Mercury's bridge connection; enabling is never automated.

Godot tool

The Godot tool controls named Godot instances over token-authenticated loopback connections served by the mercury_vulcan add-on. Each editor and worker has its own port and token, and editor operations edit scenes, nodes, scripts and resources on the selected instance.

  • MERCURY_GODOT_TOOLS=1: Arms the Boot Menu's Godot row. Without a Godot executable on the machine or pinned with MERCURY_GODOT_EXECUTABLE, the tool is withheld and the doctor's Tools withheld row says so.
  • vulcan_install and vulcan_status: Install the editor add-on, and report whether the bridge is up.
  • Instance selection: engine_jobs lists instances; an unselected editor operation never chooses the user's editor.
  • Engine jobs: Run suites, the compile and proof-drift gate, captures, profiles and frame statistics, each on a frozen copy of the project.
  • Runtime queries: Read the live scene tree or node properties, call a method or wait for a signal on a named instance.

The engine job service needs neither an open editor nor the add-on. Project file leases prevent a run from consuming changed files held by another session or agent. The script interface is mercury godot run|check|capture|frames|profile|tour|jobs|cancel|result.

Aseprite tool

The Aseprite tool drives the local Aseprite through its batch mode: every operation is one bounded run of aseprite -b, with no add-on, port, token or live connection.

  • MERCURY_ASEPRITE=1: Arms the Boot Menu row named Aseprite dev lanes. The tool joins the catalogue beside .aseprite or .ase files, or wherever the application is located.
  • status and info: Report the application's location and version, and a sprite's structure.
  • export and create: Export a sprite or sprite sheet, or create a new sprite; the ask names the source and destinations.
  • run-script: Runs Lua against the application's full scripting API. It is the one verb that may touch files outside the working directory.

Every run has a deadline. Mercury never installs, launches or updates Aseprite.

Language servers, Debugger and tests, Computer use, Command-line reference