# Pi Mobile

Prototype mobile remote control for [Pi](https://pi.dev/docs/latest) 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

```bash
npm install
```

## Run the API hub

From the repo root:

```bash
npm run dev:api
```

Or directly:

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

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

## Run the mobile app

In a second terminal:

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