Pi Live

Stable remote terminal access for Pi Coding Agent.

Pi Live turns the current Pi session into a browser-accessible terminal using a PTY + WebSocket bridge. It is designed to stay lightweight: Pi still runs as the real TUI, while desktop and mobile browsers connect to the same terminal stream through xterm.js.

This release uses our connection strategy:

• local Web UI is always available
• public access uses cloudflared when installed
• one command family only: /live

Why this architecture

Pi is a TUI. The stable way to expose it remotely is to expose the terminal, not to reconstruct Pi's chat events.

Pi Live therefore uses:

Browser/xterm.js  ← WebSocket →  PTY  ←→  Pi
Local terminal    ←──────────────┘

This avoids event-stream duplication, React chat re-render pressure, and lag inside the local Pi terminal.

Features

• PTY-based remote terminal — Pi runs inside a pseudo-terminal.
• Local terminal preserved — the original terminal remains attached to the same PTY.
• Browser terminal — powered by xterm.js.
• Mobile keybar — arrows, Enter, Tab, Esc, Ctrl+C.
• Replay buffer — reconnecting clients receive recent terminal output.
• Token auth — WebSocket and API access require a per-session token.
• Local-first — works without Cloudflare.
• Cloudflare optional — /live creates a public trycloudflare.com tunnel when cloudflared is installed.
• QR code — printed in the terminal and shown in the web UI.

Install

pi install npm:pi-live

Then reload Pi extensions:

/reload

mkdir -p ~/.pi/agent/extensions
cd ~/.pi/agent/extensions
git clone https://github.com/ketchh/pi-live.git pi-live
cd pi-live
npm install
npm run build

Usage

Start remote terminal mode from inside Pi:

/live

Pi Live will:

1. wait for Pi to become idle
2. preserve the current session file
3. shut down the current Pi process
4. restart Pi inside a PTY wrapper
5. start the local web server
6. start cloudflared if available
7. print local/public URLs and QR code

Inside remote mode:

/live status
/live stop

Commands

/live          start Pi Live remote terminal mode
/live status   show current remote access info
/live stop     stop the remote Pi session when already in remote mode

The initial release intentionally supports only the /live command family.

Cloudflare

Install cloudflared and make sure it is on PATH:

cloudflared --version

When present, Pi Live starts:

cloudflared tunnel --url http://127.0.0.1:<port>

Each session gets its own free metrics port, so multiple sessions can run concurrently.

If cloudflared is missing or fails, Pi Live continues with the local/LAN web UI.

Environment variables

PI_REMOTE_PORT=0                       # 0 = random free port
PI_REMOTE_BIND_HOST=127.0.0.1          # local-only by default
PI_REMOTE_TUNNEL=cloudflared           # cloudflared | none
PI_REMOTE_CLOUDFLARED_TUNNEL_NAME=...  # optional named tunnel
PI_REMOTE_DEBUG=1                      # print cloudflared logs

Development

npm install
npm run check
npm run build

Smoke-load the extension:

node --input-type=commonjs - <<'NODE'
const jiti = require('jiti')(process.cwd() + '/smoke.js');
const ext = jiti('./index.ts').default;
ext({ registerCommand(){}, registerMessageRenderer(){}, on(){} });
console.log('ok');
NODE

Future work

Advanced features are tracked in future.md. The core release stays minimal and terminal-first.

License

MIT