Skip to main content
Extensions add slash commands, tools for the agent, and widgets on the Mirror screen. Much of Mirror is built this way: the model picker, connections, the repository line, and memory are all bundled extensions. You can turn them off, install extensions other people have written, or have Mirror write new ones for you.
The extension API is in early beta and may change between releases. Test your extensions after upgrading Mirror.

Ask Mirror to write an extension

The quickest way to get a new extension is to describe it and let the agent write it.
  1. Run /extensions and turn on user_extensions. It’s off by default.
  2. Describe the extension you want:
  3. Read the code the agent writes to ~/.mirror/extensions/session-clock/extension.py. Ask for changes until it does what you want.
  4. Ask the agent to load it. The extension is available in every project from then on.
user_extensions gives the agent a tool for managing extensions in ~/.mirror/extensions/: In manual approval mode, each use of the tool needs your approval. External extensions also need consent before their code is imported, including in automatic approval mode. Read the code before enabling it. To write or adjust an extension yourself, see how extensions work.

Turn extensions on and off

Run /extensions to open the list. Type to filter it, use the arrow keys to select an extension, and press Enter to turn it on (●) or off (○). The list stays open so you can change several, and Escape closes it. The list also shows extensions awaiting approval (◐) and failed extensions (!), with the reason. Press Enter on an extension awaiting approval to review it. Turning an extension off removes its commands, tools, and widgets from every workspace straight away. Mirror saves your choices in ~/.mirror/config.json.
Mirror's extensions list showing enabled and disabled bundled extensions

Mirror's bundled extensions. A filled circle marks an extension as on.

Bundled extensions

Install an extension

An extension is a directory containing an extension.py file. Mirror looks for extensions in two places when it starts:
~/.mirror
extensions
<name>
extension.py
your-repo
.mirror
extensions
<name>
extension.py
Before importing new external extensions, Mirror shows their source paths in an approval list. Press Enter on entries to select them, then choose Approve selected, Approve all, or Reject all. Approve selected disables the other entries in that batch. Press Escape to skip the batch for this launch. Mirror remembers approval and rejection choices. Consent is separate from tool approval mode. Automatic tool approval doesn’t approve an extension, and an updated GitHub revision may need consent again.
An extension is Python code that runs inside Mirror with your account’s permissions. Approval mode doesn’t restrict it. A repository you clone can include extensions in .mirror/extensions/, which is why Mirror asks first.
To enable newly found extensions without being asked, start Mirror with --trust-extensions. Extensions you’ve already disabled stay disabled. To skip all extensions outside Mirror’s bundled ones for a session, start it with MIRROR_EXTENSIONS_ENABLED=false mirror. Mirror loads an extension’s code once. After you edit it, turn it off and on again in /extensions, or restart Mirror.

Install from GitHub

Run /extensions-add <GitHub URL> with the HTTPS URL of a repository that has an extension.py at its root. Review the extension’s code before enabling it. Use /extensions-update to choose installed GitHub extensions to update, or /extensions-remove to remove a source from your configuration. Removing a source unloads it and keeps its cached checkouts. Updates reload enabled extensions after any required approval. Updates are explicit; Mirror doesn’t replace a running extension just because its remote repository changed.

Install from a local directory

To register an extension without copying it into ~/.mirror/extensions/, run:
The directory must contain extension.py. Quote paths containing spaces. Paths refer to the CLI host, and relative paths start from the directory where you launched Mirror, even if you’ve switched workspaces. Mirror loads the extension from that directory. Review and approve it before use, then disable and re-enable it in /extensions after editing the code. /extensions-update only updates GitHub sources. /extensions-remove unregisters a local source without deleting its files or saved settings.

How extensions work

An extension is a Python class that subclasses mirror.cli.extension.Extension. Mirror creates one instance and shares it across all your workspaces, then calls methods on it to find out what it provides:
  • Tools. tools() returns tools the agent can call, such as a lookup in an internal service. This is the simplest kind of extension.
  • Commands and state. slash_commands() returns commands. Running a command produces an action, and reduce() applies the action to the extension’s state. Each workspace has its own copy of the state.
  • Widgets. render() draws the current state in a region of the screen, such as above the prompt.
  • Effects. reduce() and render() must return quickly, so slow work such as file or network access goes in handle_effect(). reduce() asks for it by returning an effect.
The first example below adds a tool, and the second adds a command and a widget.

Example: a tool for the agent

This extension gives the agent a tool that looks up terms in the project’s GLOSSARY.md, where each entry is a line such as - **Beam**: Reflection's model family. Save it as .mirror/extensions/glossary/extension.py:
.mirror/extensions/glossary/extension.py
Start Mirror, approve glossary when asked, and ask the agent what a term means. It calls the tool as glossary__lookup. Mirror builds the name from the extension ID and the tool name. How it works:
  • tools() runs for each workspace and receives a context whose workspace.cwd is that workspace’s directory, so each workspace reads its own GLOSSARY.md.
  • A tool has a definition property and an async execute() method. Mirror passes the model’s arguments to execute() as a JSON string, matching the parameters schema.
  • execute() returns a ToolResult with the text the model sees and whether the call succeeded.
  • needs_approval=False lets the tool run without asking in manual approval mode. Leave the default, True, for any tool that changes something.
ToolDefinition also accepts timeout_seconds, which defaults to 300.

Example: a command and a widget

This extension adds a /note command that shows a reminder above the prompt, with a separate reminder in each workspace. Save it as .mirror/extensions/workspace-note/extension.py:
.mirror/extensions/workspace-note/extension.py
Start Mirror, enable workspace-note, and run:
A custom workspace reminder displayed above the Mirror prompt

The reminder from the example extension, above Mirror's prompt.

How it works:
  1. slash_commands() registers /note. Its handler wraps the text in a RoutedExtensionAction, which Mirror delivers only to this extension.
  2. reduce() receives every action. It updates the state when the action is a _SetNote and returns the current state unchanged otherwise.
  3. render() draws the state above the prompt, chosen by render_region(), and returns None to hide the widget when there’s no reminder.
/note without text clears the reminder. available_when_busy=True lets the command run while the agent is working; commands without it wait for the turn to finish. The reminder is kept in memory only, so it resets when you open a new conversation.

Extension API

Every extension defines id() to match its directory name. Override any of these methods for the features you need: An extension module must define exactly one concrete Extension subclass, with a constructor that takes no arguments.

Workspaces and state

Mirror shares one instance of each extension across all workspaces, but keeps a separate state for each workspace. Store per-workspace values in the state, as the reminder example does, rather than as attributes on the instance. Effects keep running when you switch to another workspace. State resets when a workspace opens a conversation. To keep it, set reset_on_session_open = False.

Errors

If an extension fails to load, Mirror leaves it out and logs the error. If it raises an error while running, Mirror disables it in that workspace and shows the error above the prompt. Its commands then report that they’re unavailable. Fix the code, then turn the extension off and on in /extensions to reload it.

Extension settings

Each extension’s entry in ~/.mirror/config.json is either true or false, or an object that also holds settings:
~/.mirror/config.json
Bundled extensions use builtin/<name> keys. Discovered extensions use the absolute path of their extension.py file. Sources registered with /extensions-add use their GitHub URL or local directory path. Moving an extension can make Mirror ask about it again. The config object overrides the extension’s default_config(). Mirror applies changes to this file while it’s running.

Troubleshoot an extension

Logs can contain private code. Review them before sharing, as described in reporting a bug.
Last modified on November 3, 2026