Oppi

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

There are many clankers, and this one is mine. Oppi pairs an iPhone and iPad client with a server you run yourself for Pi coding sessions.

Oppi keeps Pi's messages, tool calls, and extension UI visible on iOS. You can review and steer sessions from native iPhone and iPad views.

Oppi supports two session paths:

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

Oppi renders extension prompts, confirmations, editor requests, status, and widgets as iOS cards, editor sheets, rows, panels, or fallback text. Pi continues to own extension behavior, tools, providers, and session files.

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

The Workspaces tab opens All Sessions for the active server. It keeps Your Turn and Working at the top, groups recent stopped sessions by day, and shows each workspace name. Use the sidebar or drawer to manage saved Agents and schedules, collapse the workspace list, open App Settings, or browse a workspace's sessions, files, and settings.

The create and edit sheets for Agents, schedules, and workspaces can open an Oppi Control session. Oppi Control uses a normal timeline and the Default Agent. Describe the change, review the proposed oppi command, and approve the configuration change before Oppi applies it. You can also use the forms in the same sheets.

Quick Session starts a session without opening a workspace first. Launch it from Oppi, Control Center, the Action Button, Spotlight, Siri, or Shortcuts. The Shortcuts New Session action can add optional text and one image to the composer.

The iOS share extension accepts text, URLs, images, and files. Choose a paired-server workspace in its Quick Session composer, then start the session from the share sheet.

You need Node.js 24+ and at least one Pi provider configured through pi auth or an API key such as ANTHROPIC_API_KEY. Self-signed TLS on Linux 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, starts local HTTPS/WSS, and prints a pairing QR code and invite link. In the iOS TestFlight app, choose Pair Nearby Mac, Scan QR Code, or Enter manually. You can also open the printed oppi://connect link on your phone.

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

With the default HTTP/TLS transport, the phone must reach the server over LAN, Tailscale, or a public hostname. For remote HTTP pairing, include the host in the invite:

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

Iroh mode connects through a signed server endpoint ID, either directly or through an Iroh relay. It works without an Oppi host, port, TLS certificate, LAN, or Tailscale:

OPPI_IROH_TRANSPORT=1 OPPI_IROH_INVITE_MODE=irohOnly oppi serve

Oppi rejects HTTP fallback for an Iroh-only invite and its device token.

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).

To include your Tailscale host in the first QR code from serve, run:

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

Use the repository installer only when developing Oppi or testing unreleased server changes:

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

For regular use, install from npm. Then update with npm install -g oppi-server@latest.

If you used oppi server install, a LaunchAgent starts the server at login and restarts it after a crash. Manage it with:

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

After installing oppi-server from npm, use these common commands:

oppi serve [--host <h>]      # start server
oppi init                    # interactive first-time setup
oppi pair [--host <h>]       # regenerate pairing QR + invite link
oppi status                  # server, network, and pairing status
oppi doctor                  # security and environment diagnostics
oppi workspace ...           # list/create/update/delete workspaces
oppi worktree ...            # list/create/open/preview/remove worktrees
oppi session ...             # create/send/watch/wait/inspect/resume/fork/delete sessions
oppi agent ...               # manage saved Agents
oppi schedule ...            # manage schedules and run history
oppi server ...              # install/status/restart/stop/uninstall launchd service
oppi config ...              # show/get/set/validate config
oppi token rotate            # rotate owner bearer token
oppi update                  # update the npm-installed server and CLI

You can manage saved Agents and schedules from the Oppi sidebar or server CLI/API. Saved Agents store reusable definitions and can use one Unicode emoji or SF Symbol name as an icon. The icon appears in Agent management and sessions started from that Agent. Clearing it restores the generic Agent icon.

Schedules support at, every, and cron triggers. Each schedule can target a workspace, saved Agent, or existing session. Oppi keeps run history for manual and approved automatic runs.

Control sessions pass Agent and schedule changes through size-limited --definition-json arguments instead of temporary files. Run oppi --help or see server/README.md for all commands.

The macOS app, human users, and managed host sessions share the globally installed oppi command. The app does not bundle another server. Install or update it first:

npm install -g oppi-server@latest

oppi init, local status, and pairing work before you pair a phone. Workspace, session, Agent, and schedule commands require the local owner credentials created during setup.

• Contributing - open an issue before proposing code changes
• Changelog - release history and versioning policy
• Server README - server setup, Docker, development
• Onboarding and pairing - first-run 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 rules
• 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

• Architecture - cross-system architecture map
• Server architecture - routes, streams, runtime ownership, and storage
• Client architecture - Apple stores, transports, and the chat timeline pipeline
• Extension native UI - native extension UI contract
• Testing - standard test commands
• Model selection - chat model selection precedence
• Session tree semantics - session tree and fork semantics
• Protocol snapshots - wire fixtures and stream topology

MIT