pi-mobile/README.md

Pi Mobile

Prototype mobile remote control for Pi coding agents.

Phone connects to a hub running on your computer over the local network. The hub embeds the Pi SDK in-process and exposes session management plus streaming chat over Socket.IO.

Prerequisites

• Node.js 20+
• Pi installed and authenticated on the host machine (pi CLI with /login or provider API keys)
• Expo Go on your phone (or iOS Simulator / Android emulator)
• Phone and computer on the same LAN

Project structure

apps/api/      Express + Socket.IO hub with Pi SDK
apps/mobile/   Expo Router mobile app

Setup

npm install

Run the API hub

From the repo root:

npm run dev:api

Or directly:

cd apps/api
npm run dev

The server listens on 0.0.0.0:8787 by default and prints LAN URLs on startup.

Custom port:

npm run start -w @pi-mobile/api -- --port 9000

Run the mobile app

In a second terminal:

npm run dev:mobile

Scan the QR code with Expo Go, then:

1. Enter your computer's LAN IP and port (8787)
2. Tap Connect
3. Create a session by choosing a folder under ~/
4. Send prompts and watch streamed assistant text + tool activity
5. Resume persisted Pi sessions from the list

API surface

HTTP

• GET /health — liveness check
• GET /fs/list?path=~ — folder-only explorer rooted at home

Socket.IO (client → server)

Event	Payload
sessions:list	—
runtime:create	{ cwd, name? }
runtime:open	{ sessionFile }
runtime:attach	{ runtimeId }
chat:prompt	{ runtimeId, message }
chat:abort	{ runtimeId }

Socket.IO (server → client)

Event	Payload
sessions:list:result	{ persisted, live }
runtime:created / runtime:opened	{ runtimeId, sessionId, cwd, sessionName?, sessionFile? }
chat:event	{ runtimeId, event }
error	{ message }

Notes

• Security/auth are intentionally out of scope for this prototype.
• The folder browser only exposes directories under your home folder.
• Pi credentials are read from the host environment / Pi auth storage — the mobile app does not handle login.
• Multiple live runtimes can run concurrently; switch between them from the Sessions screen.

Success checklist

• Connect from phone via LAN IP
• Browse folders starting at ~/
• Create a new Pi session
• Send a prompt and see streamed text + tool rows
• Resume a persisted session
• Open a second live runtime without stopping the first