oppi-mirror

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

Install

pi install npm:oppi-mirror

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

pi update --extension npm:oppi-mirror

If Pi is already running, reload extensions:

/reload

Use

Start the Oppi server so $OPPI_DATA_DIR/run/oppi.sock exists. 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 connects over the owner-only Unix socket at $OPPI_DATA_DIR/run/oppi.sock. That upgrade is bearer-free. The network HTTPS/WSS listener does not expose /mirror/v1/bridge.

Override the socket for one process:

OPPI_MIRROR_SOCKET=/path/to/oppi.sock pi

Use a network URL only for explicit debug overrides. The live server rejects owner-token WSS upgrades on /mirror/v1/bridge:

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, ask, prompts before creating a workspace when the terminal cwd is outside an Oppi workspace. 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.

The terminal owns session replacement. 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 do not become 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