oppi-mirror

oppi-mirror is a Pi extension that mirrors an interactive terminal pi session into Oppi. The terminal keeps execution ownership; Oppi can watch output, send prompts, steer the active turn, queue follow-ups, answer extension UI, and stop or abort through the bridge.

Install

pi install npm:oppi-mirror

Update an existing install before starting a matching Oppi server release:

pi update --extension npm:oppi-mirror

If Pi is already running, reload extensions:

/reload

Use

Start the Oppi server once so the extension can read ~/.config/oppi/config.json, then start Pi in an interactive terminal:

pi

Check or control the bridge from Pi:

/oppi-mirror status
/oppi-mirror stop
/oppi-mirror start

Configuration

By default, the extension reads the local Oppi server URL and token from ~/.config/oppi/config.json.

Override the connection for one process:

OPPI_MIRROR_URL=https://127.0.0.1:7749 \
OPPI_MIRROR_TOKEN=your-token \
pi

Configure startup and missing-workspace behavior in ~/.pi/agent/settings.json:

{
  "oppiMirror": {
    "autoStart": false,
    "workspaceCreation": "ask"
  }
}

workspaceCreation accepts ask, always, or never. The default is ask: if the terminal cwd is not inside an Oppi workspace, Pi prompts before creating one. Approved workspaces use the nearest parent git repo as hostMount; without a git repo, they use the terminal cwd.

For one process:

OPPI_MIRROR_AUTO_START=false \
OPPI_MIRROR_WORKSPACE_CREATION=never \
pi

What it supports

Mirror supports prompts, steering and follow-up messages, stop or abort, queue updates, model and thinking changes, tree navigation, and standard Pi extension UI flows such as select, confirm, input, editor, notify, title, status, widgets, and working-row customization.

Session replacement stays terminal-owned. Use terminal Pi for /new, /fork, and session switching.

Requirements

• Oppi server 0.45.0 or newer
• Interactive terminal pi; print, JSON, RPC, and server-owned SDK sessions are not mirror sessions

See the full mirror contract and compatibility matrix in the Oppi repo: https://github.com/duh17/oppi/blob/main/docs/oppi-mirror.md