pi-web (Remote Control Your Pi)

Drive your pi coding agent from any browser on your network — laptop, phone, or tablet.

Warning

pi-web is currently in beta. Things will change and break!

Screenshots

Desktop — dark mode


Desktop — light mode


Mobile PWA

How It Fits Together

 pi (terminal)                 Browser (phone / tablet / laptop)
      │                                │
      │  writes JSONL                  │  HTTP + SSE
      ▼                                ▼
 ~/.pi/agent/sessions/  ←───  pi-web (Go HTTP server)
                                      │
                    ┌─────────────────┼─────────────────┐
                    │                 │                 │
              pi --mode rpc      fsnotify         tailscale serve
            (per‑session       (live reload)      (remote HTTPS
             chat worker)                           via MagicDNS)

• pi writes conversation JSONL to ~/.pi/agent/sessions/ as it works.
• pi-web is a Go server that reads those files, renders them in the browser, and streams live updates via SSE.
• pi --mode rpc workers handle browser-initiated chat — one per session, reaped after 10 min idle.
• fsnotify watches the sessions directory so the browser reloads within milliseconds of new output.
• Tailscale Serve publishes the localhost server as an HTTPS endpoint on your tailnet.

Install

pi install npm:@ygncode/pi-web

That's it — it downloads the binary, sets up auto‑start, and registers the /web, /remote, /refresh, and set_tab_title commands.

Once installed, open http://127.0.0.1:31415 in your browser. From pi, use /web to open the current session in your browser instantly. If Tailscale is running on your machine, pi-web automatically publishes an HTTPS endpoint on your tailnet — use /remote from pi to get a QR code and URL for any device on your tailnet.

For manual installs, binary downloads, or building from source, see docs/install.md.

Pi Integration

After pi install npm:@ygncode/pi-web, you get:

Command	What it does
/web	Open the current session in your browser (SSH-aware: skips browser and shows URL only)
/pi-web	Show status, version, start/stop/restart the server, or update
/remote	Show a QR code and URL for remote access over Tailscale
/refresh	Pull new messages written from remote browsers back into the terminal session
set_tab_title	Tool that updates the session title; also auto‑derives a short title from each user message

The package also installs the pi-web binary to ~/.pi/agent/bin/pi-web and sets up auto-start on login.

Auto-Start on Login

The pi install npm:@ygncode/pi-web command sets this up automatically:

OS	Mechanism
macOS	launchd plist at ~/Library/LaunchAgents/com.pi-web.plist
Linux	systemd user service at ~/.config/systemd/user/pi-web.service

To set a token for remote access, create ~/.config/pi-web/env:

PI_WEB_TOKEN=your-token-here

For more details (manual setup, custom ports, non-loopback binds), see docs/install.md.

Development

make setup   # install frontend deps and download Go modules
make check   # frontend test/build + Go test/vet
make build   # setup if needed, build frontend, then build ./pi-web

License

MIT