Oppi

Use pi from iPhone and iPad.
TestFlight · Demo video · Screenshots

There are many clankers and this one is mine: an iPhone/iPad client and self-hosted server for Pi coding agent sessions.

The goal is to bring Pi's transparency and extensibility to native iOS, render clanker output and tool use nicely, and make it easy to review and steer sessions from mobile devices.

How it works

Oppi has two session paths:

• SDK sessions: the server embeds the Pi SDK in-process, with tool execution, streaming, and standard Pi extension UI.
• TUI bridge: the oppi-mirror extension projects a terminal-owned Pi session into Oppi.

Extension prompts, confirmations, editor requests, status, and widgets render as iOS cards, editor sheets, rows, panels, or fallback text. Extension behavior, tools, providers, and session files stay in Pi.

┌─────────────────────┐
│   iPhone / iPad     │
│        Oppi         │
└──────────┬──────────┘
           │ HTTPS / WSS
           │ session stream + Pi extension UI
┌──────────▼──────────┐
│     oppi-server     │
│       Node.js       │
└──────────┬──────────┘
           │ pi SDK / TUI
┌──────────▼──────────┐
│    LLM provider     │
│      + tools        │
└─────────────────────┘

Quick start

Requires Node.js 23.6+ and at least one Pi provider configured (pi auth, or an API key such as ANTHROPIC_API_KEY). Linux self-signed TLS also requires openssl on PATH.

Install and start:

npm install -g oppi-server
oppi serve

On first run, oppi serve creates ~/.config/oppi/, generates owner credentials, boots local HTTPS/WSS, and prints a pairing QR code plus invite link. In the iOS TestFlight app, pair with one of the visible options: Pair Nearby Mac, Scan QR Code, or Enter manually. Opening the printed oppi://connect invite link on the phone also starts pairing.

To run Oppi as a background service on macOS:

oppi server install
oppi server status

Upgrade or uninstall with npm:

npm install -g oppi-server@latest
npm uninstall -g oppi-server

Your phone and server must be reachable over LAN, Tailscale, or a public hostname. For remote pairing (Tailscale or VPS), generate invites with an explicit host:

oppi pair --host <hostname-or-ip>

Notes:

• --host expects host/IP only (no https://, no :port).
• Invites are single-use and short-lived (90 seconds by default). If pairing fails, generate a fresh invite.
• Invite port comes from server config (oppi config get port).

If you want first-run QR output from serve to already use your Tailscale host, start with:

oppi serve --host <your-host>.ts.net

Source checkout (development)

Use the repo bootstrapper only when you are developing Oppi or testing unreleased server changes:

git clone https://github.com/duh17/oppi.git
cd oppi
bash install.sh

For regular use, prefer the npm route above so updates are just npm install -g oppi-server@latest.

Background service (macOS)

If you used oppi server install, the server runs as a LaunchAgent that starts on login and restarts on crash. Manage it with:

oppi server status     # check if running
oppi server restart    # restart
oppi server uninstall  # remove

Commands

Use oppi ... after installing oppi-server from npm.

oppi serve [--host <h>]      start server
oppi pair [--host <h>]       regenerate pairing QR
oppi status                  server config overview
oppi doctor                  check prerequisites
oppi update                  update mutable runtime dependencies
oppi update --self           update the global npm server install
oppi init                    interactive first-time setup
oppi config show             current config
oppi config set <k> <v>      update config value
oppi config validate         validate config file
oppi token rotate            rotate owner auth token
oppi agent list              list saved Agent definitions
oppi agent create            create a saved Agent from flags or JSON
oppi session create --agent  launch a saved Agent in a workspace
oppi schedule list           list saved schedules
oppi schedule create         create an at/every/cron schedule
oppi schedule run <id>       run a schedule now
oppi schedule runs <id>      inspect schedule run history
oppi server install          install LaunchAgent (macOS)
oppi server uninstall        remove LaunchAgent
oppi server status           check background service
oppi server restart          restart background server
oppi server stop             stop background server

Saved Agents and schedules are server CLI/API features. Saved Agents hold reusable Agent definitions; schedules store at/every/cron triggers plus an action and keep run history for manual or approved automatic runs.

Mac app shell (experimental)

The macOS app is an experimental shell with early configuration views. It is not a supported Pi session UI yet.

For normal use, run the server with the CLI above and pair from the iPhone/iPad app.

Docs

• Changelog - release history and versioning policy
• Server README - server setup, Docker, development
• Onboarding and pairing - intended first-run user flow
• Deep links - custom URL schemes for pairing, workspaces, and sessions
• Config schema - all config options
• Dictation / ASR - server dictation setup
• Voice replies / TTS - voice extension setup
• Extensions - Oppi-specific extension behavior, workspace filtering, and mobile rendering gotchas
• Attachment rendering - message and tool-output rendering for image, audio, video, and file attachments
• Document viewers - full-screen reading controls for markdown, code, diffs, terminal output, and rendered documents
• TUI session bridge - live terminal Pi sessions in Oppi and the separate oppi-mirror package
• Sandbox workspaces - Gondolin VM isolation, network boundaries, tools, and safe defaults
• Custom themes - creating color themes for the iOS app
• Telemetry and diagnostics - privacy controls, storage paths, latency, and reliability metrics
• Security - security model and privacy

License

MIT