Mercury CLI
Documentation

Extend

Extensions

An extension is a folder with one manifest, mercury-extension.json, that names it, versions it, and says what it adds to Mercury and what it needs from the machine. Mercury reads nothing in the folder that the manifest does not declare. Extensions come from sources you add. Mercury ships with no source and never adds one on its own.

An extension's id is <name>@<source label>. The board is /extensions, and the command-line verbs are mercury extensions <verb>.

Extension sources

A source is a git repository on any host, a local folder or an archive. Its root carries one of two files:

  • mercury-extensions.json: A catalogue of several extensions, each named with its version, a line of description, and either path inside the source or git plus an optional ref. An entry that disagrees with the fetched manifest refuses the install.
  • mercury-extension.json: A single extension. The repository is the source.

Contributions

  • Skills: Directories whose child folders each hold a SKILL.md, registered as /<name>:<skill>.
  • Commands: Directories of <cmd>.md prompt files, registered as /<name>:<cmd>.
  • Agents: Directories of <agent>.md definitions, registered as agent type <name>:<agent>. Privilege-raising front matter is ignored with a health note, and an extension agent runs under the session's permission mode.
  • Hooks: Command hooks, each time-bounded with bounded output. A failing hook is logged, never fatal to the session.
  • Servers: MCP servers over stdio, http or sse, connected as ext:<name>:<server>. Their tools pass the permission engine like any MCP tool.
  • Language: Language servers in Mercury's own configuration shape, started as ext:<name>:<server>.
  • Channels: The extension's servers allowed to post channel messages into the session after approval. Posts from an undeclared server are dropped.
  • Keybindings: Default chords for the extension's own commands and skills, applied only where your keybindings leave the chord free.

Manifest fields

  • name: Required. Lowercase letters, digits and hyphens, 1 to 40 characters, starting with a letter or digit.
  • version: Required. Any non-empty string without whitespace. It keys updates and approval.
  • description: Required. One line of at most 200 characters.
  • mercury: Optional. A version floor, >=x.y.z. Unmet, the extension is broken with the reason.
  • contributes: Optional. What the extension adds, in the kinds above.
  • needs: Optional. binaries on PATH, env variables, network hosts and configurable options. A missing binary or unset variable makes the extension partial with the reason.
  • module: Reserved. This build loads declarative extensions.

Every path in the manifest stays inside the extension root. An unknown top-level key is a warning at load and an error under mercury extensions validate. An unknown key inside contributes or needs is an error at load. A sensitive option lives in the secure store, appears as a placeholder in prose the model reads, and reaches only hook and server environments.

Add an extension source

To add an extension source, follow these steps:

  1. Run mercury extensions add <url|path|archive>, or press a on the sources tab of /extensions.

Mercury checks the blocklist, fetches, validates, labels and records the source. Nothing is installed.

Install an extension

To install an extension, follow these steps:

  1. Open /extensions.
  2. Select the extension in its source.
  3. Press i.
  4. Read the approval card: what the extension runs, adds and needs.
  5. Approve.

Mercury fetches the copy, records the approval and turns the extension on.

mercury extensions install <name>[@label] does the same from the command line, and --yes is the only scripted approval. Approval is tied to a hash of contributes and needs: a version bump that changes nothing carries approval over, and a changed command line, server or need shows the diff and asks again.

Refresh and apply an update

To refresh and apply an update, follow these steps:

  1. Select the source on the /extensions board.
  2. Press u to refresh it.
  3. Select the extension with an update.
  4. Press U.
  5. Approve the changed contributions, if the card asks again.

Mercury applies the update and keeps the previous version until the first clean load.

Refreshing a source, with u or mercury extensions check, is the only act that discovers a newer version. mercury extensions update <id> --previous swaps back to the previous version.

Other controls

  • list and sources: The installed roster and the sources, each with state.
  • remove <label>: Removes a source. Its installed copies keep working unless --and-extensions removes them too.
  • approve <id>: The approval card for an installed-off or found extension.
  • enable <id> and disable <id>: The switch, everywhere or with --project.
  • block and unblock: The blocklist.
  • uninstall <id>: Removes everything, or keeps the data with --keep-data.
  • validate <path>: The maker's linter.
  • init <name>: Scaffolds an extension, or a source root with --source.

The MCPs & Skills menu on the Boot face adds a per-repository master switch, and a session is served an extension only when both switches agree.

Health lives on the row, always with the reason: on, partial or broken. /health carries one extensions row.

MCPs and skills, Hooks, Language servers, Health check