---
slug: "pi-live"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/ketchh/pi-live@main/README.md"
repo: "https://github.com/ketchh/pi-live"
source_file: "README.md"
branch: "main"
---
# Pi Live

**Turn your current Pi Coding Agent session into a polished remote web interface in seconds.**

Pi Live is a minimal, mobile-friendly Pi extension that exposes the current session through a local web UI and, when available, a public Cloudflare tunnel with QR code sharing.

---

## Why Pi Live

Pi Live focuses on one job only:

- **instant local web UI** for the current Pi session
- **optional public sharing via `cloudflared`**
- **mobile-first review experience** for messages, thinking, and tool activity
- **zero-friction activation** through a single command: `/live`

It intentionally avoids feature bloat in the initial release.

---

## Core release scope

This public release keeps the core minimal:

- the current Pi Live page and integrated review UI
- a **local WebUI** always available
- a **public tunnel only when `cloudflared` is installed**

Anything more advanced is tracked in [`future.md`](https://github.com/ketchh/pi-live/blob/HEAD/future.md).

---

## Quick install

```bash
pi install npm:pi-live
```

Then start Pi or reload extensions with:

```txt
/reload
```

---

## Quick start

### 1. Open the local web UI

Pi Live starts a local web server automatically when Pi loads the extension.

Use:

```txt
/live status
```

Pi will show the active local URL, for example:

```txt
http://localhost:12345/
```

Open that in your browser on the host machine.

### 2. Publish it publicly with Cloudflare

If `cloudflared` is installed and available in `PATH`:

```txt
/live
```

Pi Live will:

- start a public Cloudflare tunnel
- generate a shareable URL
- generate a QR code
- show both in Pi and in the web UI

---

## Commands

```txt
/live             publish via cloudflared and show URL + QR
/live status      show current live state
/live stop        stop the public tunnel
/live restart     recreate the public tunnel
/live token       rotate the access token and regenerate URL + QR
```

---

## Features

### Local-first web UI

Even without any public tunnel, Pi Live gives you a browser-based view of the current session.

### Mobile-friendly review flow

The UI is designed for quick reading and navigation on mobile:

- chat tree for fast jumps
- compact session feed
- message / tools filtering
- adjustable font size
- optional truncation for non-message blocks

### Secure public access

Public access uses a random token embedded in the URL fragment:

```txt
/#token=...
```

That means:

- the token is required for websocket access
- the token is not sent in the initial HTTP path/query
- local and public URLs stay clearly separated

---

## Requirements

### Required

- Node.js 20+

### Optional

- `cloudflared` for public tunnel support

Check installation with:

```bash
cloudflared --version
```

If Cloudflare is not installed, Pi Live still works perfectly in **local WebUI mode**.

---

## Environment variables

```bash
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_HISTORY_DIR=~/.pi/agent/remote-sessions
PI_REMOTE_TOKEN=...                    # optional fixed token
PI_REMOTE_SHOW_THINKING=0
PI_REMOTE_MAX_HISTORY_EVENTS=5000
PI_REMOTE_DISABLE=0
PI_REMOTE_CLOUDFLARED_TUNNEL_NAME=...  # optional named tunnel
```

---

## Development

```bash
npm install
npm run check
npm run build
```

---