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 run without asking, and every other verb asks.

Code-editor integration

mercury acp: Serves an editor over the Agent Client Protocol, with a runner child for each session. When the ACP client advertises fs.readTextFile, fs.writeTextFile or terminal, Read reads from the editor buffer, Write and Edit route through the editor with a read-back after the write, and Bash runs in the editor terminal.
mercury bridge install, mercury bridge status and mercury bridge uninstall: Install, check or remove the VS Code extension.
VS Code extension: Runs Mercury in the editor over the Agent Client Protocol: chat, sessions, agents, artifacts and reviews, with the editor's selection and diagnostics sent along with each prompt. The extension is licensed under the Apache License 2.0 (Apache-2.0) and packages LICENSE.txt and NOTICE in its VSIX.

With nothing signed in, the editor lists Sign in from a terminal when it supports terminal sign-in. It opens Mercury's sign-in screen in a terminal: pick a provider and finish there. mercury acp --login opens that screen on its own and exits once sign-in is stored.

The editor also lists Claude subscription, which opens the sign-in page in your browser. Editors that show links also list device-code sign-ins for Kimi, Hugging Face, xAI, Meta, Nous Portal and OrcaRouter, with the code to enter.

Install the VS Code extension

Run mercury bridge install to install the VS Code extension, mercury bridge status to check it, and mercury bridge uninstall to remove it.

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: Turns on 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. unity_bridge_uninstall removes all three.
unity_status: Probes the flag, the package and whether it is up to date, the token, reachability, the client state and any port mismatch between the halves.
MERCURY_UNITY_BRIDGE_PORT: The loopback port, 6011 by default.
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: Turns on 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_bridge_uninstall removes that directory whole.
blender_status: Reports installation and connection facts; an answering bridge proves that Blender is open with the add-on enabled.
MERCURY_BLENDER_BRIDGE_PORT and MERCURY_BLENDER_BRIDGE_ADDON_DIR: The loopback port, 6012 by default, and a pin for the add-on directory.
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, mutation and execution verbs refuse with RENDER_ACTIVE; read operations, including render_state, remain available.
python_run: Runs Python inside Blender with full bpy authority; the ask shows 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:

Open Blender's Edit menu.
Open Preferences.
Open Add-ons.
Search for Mercury.
Enable the add-on.

The add-on can then answer Mercury's bridge connection.

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: Turns on the Boot Menu's Godot control surface (VULCAN) row. Without a Godot executable on the machine or pinned with MERCURY_GODOT_EXECUTABLE, the tool is withheld and /health lists it under Tools withheld.
vulcan_install and vulcan_status: Install the editor add-on and report whether the bridge is up.
Instance selection: engine_jobs lists instances; an editor operation needs a selected instance and never picks your editor on its own.
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.

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: Turns on the Boot Menu row named Aseprite dev lanes. The tool joins the catalogue beside .aseprite or .ase files, or wherever the application is located.
MERCURY_ASEPRITE_BIN: Pins the application's executable. A broken pin refuses by name.
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.
draw: Draw an ordered batch of pixels, lines, rectangles, ellipses, circles and flood fills on named layers and frames, using palette indices or RGBA colours.
parts: Create layers and groups, show or hide them, reorder siblings and copy independent cels to other frames.
render: View a PNG of a frame, tag or every frame side by side. Integer scaling enlarges the preview without resizing the sprite.
describe: Read layer paths, visibility, stacking order, cel bounds, frame durations, tags and palette size.
palette-check: Find colours outside a sprite's palette, a .gpl or .hex file, or a supplied colour list. The result gives counts and positions without changing colours.
run-script: Runs Lua against the application's full scripting API. It is the one verb that may touch files outside the working directory.

draw and parts ask once for the ordered batch and return a PNG preview by default. They save only when every operation and the requested render succeed; a failure leaves the original sprite unchanged. Frames and coordinates are zero-based. Drawing into a linked cel leaves its other frames unchanged. Previews are temporary; use export to keep a project image.

Every run has a deadline: 15 seconds for status and info, 30 for create, 60 for export, the art operations and run-script by default, where timeoutMs caps at 120,000 milliseconds. Output is capped with the truncation counted, and Aseprite's own errors are shown as written. Mercury drives the installed application as it finds it and does not install, launch or update it.

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