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.-
Run
/extensionsand turn onuser_extensions. It’s off by default. -
Describe the extension you want:
-
Read the code the agent writes to
~/.mirror/extensions/session-clock/extension.py. Ask for changes until it does what you want. - 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 bundled extensions. A filled circle marks an extension as on.
Bundled extensions
Install an extension
An extension is a directory containing anextension.py file. Mirror looks for extensions in two places when it starts:
~/.mirror
extensions
<name>
extension.py
your-repo
.mirror
extensions
<name>
extension.py
--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:
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 subclassesmirror.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, andreduce()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()andrender()must return quickly, so slow work such as file or network access goes inhandle_effect().reduce()asks for it by returning an effect.
Example: a tool for the agent
This extension gives the agent a tool that looks up terms in the project’sGLOSSARY.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
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 acontextwhoseworkspace.cwdis that workspace’s directory, so each workspace reads its ownGLOSSARY.md.- A tool has a
definitionproperty and anasync execute()method. Mirror passes the model’s arguments toexecute()as a JSON string, matching theparametersschema. execute()returns aToolResultwith the text the model sees and whether the call succeeded.needs_approval=Falselets 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
workspace-note, and run:

The reminder from the example extension, above Mirror's prompt.
slash_commands()registers/note. Its handler wraps the text in aRoutedExtensionAction, which Mirror delivers only to this extension.reduce()receives every action. It updates the state when the action is a_SetNoteand returns the current state unchanged otherwise.render()draws the state above the prompt, chosen byrender_region(), and returnsNoneto 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 definesid() 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, setreset_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
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.