Mirror extensions

​

Enable or disable an extension

1. Run /extensions to open the picker.
2. Type to filter the list, then use the arrow keys to select an entry.
3. Press Enter to toggle it. The picker stays open so you can change several entries.
4. Press Escape when finished.

• Bundled entries use keys such as builtin/editor.
• External entries use the resolved absolute path to their extension.py file.
• Moving an external extension can trigger a new trust decision.

​

Bundled extensions

• For command arguments, see the CLI reference.
• For server configuration, see MCP servers.

​

Install an external extension

• Outside a repository, Mirror checks the launch directory for project extensions.
• Discovery uses the launch directory. Switching workspaces does not scan a new directory for additional extensions.

1. Add the extension.py file in one of these locations.
2. Start Mirror.
3. Review the code and select Enable if you trust it.

• Use /extensions to change the decision later.
• After editing Python source, toggle the extension off and on, or restart Mirror.
• Saving the file alone does not reload its code.

• Newly discovered external extensions are enabled without the consent prompt.
• Existing disabled choices are preserved.

MIRROR_EXTENSIONS_ENABLED=false mirror

​

Example: a workspace reminder

mkdir -p .mirror/extensions/workspace-note

"""Keep a short workspace reminder above the Mirror prompt."""

from __future__ import annotations

import dataclasses
from collections.abc import Sequence
from typing import override

from prompt_toolkit.layout import containers, controls

from mirror.cli import actions, commands, extension, state


@dataclasses.dataclass(frozen=True)
class _SetNote(actions.ExtensionAction):
  text: str


class WorkspaceNote(extension.Extension[str, None, None]):
  supports_local = True

  @classmethod
  @override
  def id(cls) -> str:
    return 'user/workspace-note'

  @staticmethod
  @override
  def initial_state() -> str:
    return ''

  @override
  def render_region(self) -> extension.RenderRegion:
    return extension.RenderRegion.WIDGET_ABOVE_PROMPT

  @override
  def slash_commands(self) -> Sequence[commands.CommandDef]:
    return (
      commands.CommandDef(
        'note',
        'Set a workspace reminder; omit text to clear it',
        lambda _context, text: actions.RoutedExtensionAction(
          self.id(), _SetNote(text.strip())
        ),
        arguments=commands.OptionalArguments('[text]'),
        available_when_busy=True,
      ),
    )

  @override
  def reduce(
    self, global_state: state.State, action: actions.Action
  ) -> tuple[str, tuple[extension.PrivateEffect[None], ...]]:
    current = self.require_state(global_state)
    if (
      isinstance(action, actions.RoutedExtensionAction)
      and action.extension_id == self.id()
      and isinstance(action.action, _SetNote)
    ):
      return action.action.text, ()
    return current, ()

  @override
  def render(
    self, global_state: state.State, extension_state: str
  ) -> containers.AnyContainer | None:
    if not extension_state:
      return None
    return containers.Window(
      controls.FormattedTextControl([('class:footer', f'Note: {extension_state}')]),
      height=1,
    )

1. Start Mirror.
2. Enable workspace-note when prompted.
3. Set a reminder with /note:
   /note Check regression tests before committing.
   

​

How the example works

1. slash_commands() registers the command. Its handler returns a RoutedExtensionAction containing the text.
2. reduce() applies that action to this workspace’s extension state.
3. render() draws the resulting reminder above the prompt.

• Keep id() stable and unique.
• Define one concrete Extension subclass in the module, with a no-argument constructor.
• Set supports_local = True for local workspaces.

​

Extension API

• Keep file and network operations out of reduce() and render().
• Emit an effect and do the work in handle_effect() so rendering remains responsive.

• Expose a ToolDefinition.
• Implement async execute(arguments: str) -> ToolResult. The argument string contains JSON.

​

Extensions across workspaces

​

Ask Mirror to create an extension

Create a user extension named session-clock that shows elapsed time
below the prompt. Keep its ID stable. Show me the source before loading it.

• Review the generated code before asking Mirror to load it.
• create only writes the scaffold. Loading is a separate step.
• If you want tool-call review while the agent works, choose manual approval with /permissions.

​

Troubleshoot an extension