# 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

```bash
pi install npm:oppi-mirror
```

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

```bash
pi update --extension npm:oppi-mirror
```

If Pi is already running, reload extensions:

```text
/reload
```

## Use

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

```bash
pi
```

Check or control the bridge from Pi:

```text
/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:

```bash
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`:

```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:

```bash
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