--- slug: "narumitw-pi-web" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/narumiruna/pi-web@main/README.md" repo: "https://github.com/narumiruna/pi-web" source_file: "README.md" branch: "main" --- # pi-web ## Quick start Run once: ```bash npx --yes @narumitw/pi-web@latest ``` Or install globally: ```bash npm install -g @narumitw/pi-web pi-web ``` Open the printed URL (without `--port`/`PORT`, it starts at and uses the next free port if busy). As a Pi extension: ```bash pi install npm:@narumitw/pi-web # then in pi: /pi-web ``` `/pi-web` starts the local service and live-syncs the current Pi session. Local-first TypeScript web UI for [Pi Coding Agent](https://github.com/earendil-works/pi). ## Features - Chat with Pi sessions from the browser, including streaming replies, abort, compact, follow-up/steer, and image prompts. - Resume, rename, delete, export, fork, and inspect saved sessions from `~/.pi/agent/sessions`. - Switch model, thinking level, active tools, slash commands, prompt templates, and skills. - Paste images directly into the chat box with `Ctrl+V`, preview attachments, and send them with the prompt. - Use a web terminal tab backed by a persistent local shell, save command snippets, and send recent output back to the chat draft. - Browse workspace files, read text files, preview images, and auto-refresh file changes. - Review git diffs with per-file and per-hunk revert, create checkpoints (including automatic pre-rewind safety checkpoints), rewind local changes, and run validation commands from package scripts. - Visualize agent task flow as Plan → Act → Verify, import GitHub issues, manage kanban task cards, and create draft PRs. - Preview localhost browser apps, attach screenshots, export sessions as HTML/JSON/Markdown with secret redaction, replay exports, and run golden-task evaluations (dry-run or full agent mode) with accept/reject review. - Use the Control room tab for auth/API keys, usage/cost estimates, diagnostics/troubleshooting, permissions safe mode, MCP/external tool config, repo rules, model switching, tool toggles, model-invoked skill toggles, and bookmarks. - Run in one Fastify process with a Vite/React client and a small compatibility layer for the routes this UI uses. ## Local development Requirements: Node.js 22+, npm, and a configured Pi install/API key. ```bash npm install npm run dev ``` Open the Vite UI at . The API server runs on `127.0.0.1:30141`. Production build/run: ```bash npm run build npm start ``` Open . CLI workspace precedence is `--cwd`, then `PI_WEB_CWD`, then `WORKSPACE_ROOT`, then the current directory. ```bash cd /path/to/project && pi-web pi-web --cwd /path/to/project --port 30141 node dist/server/cli.js --cwd /path/to/project --port 30141 ``` Each pi-web process is scoped to that effective startup workspace. Chat history and full-message search include only sessions whose stored `cwd` exactly matches the normalized startup path; sibling directories, child directories, and Git worktrees are not included. Sessions from other workspaces remain on disk and appear when pi-web is started for their workspace. The workspace path shown in the sidebar is read-only. New chats use the startup workspace, and pi-web does not offer worktree-session creation because a worktree has a different `cwd`. Existing worktree management APIs remain available. ## Docker Production-like compose uses `compose.yml` and stores data under `./data`: ```bash just up # docker compose up -d --build --remove-orphans just down # docker compose down --remove-orphans ``` Development compose uses `compose.dev.yml` and mounts this repo at `/workspace`: ```bash just devup just devdown ``` Open . The image installs `uv`, Rust/Cargo, and the latest uv-managed Python by default. Pin versions with build args: ```bash UV_VERSION=0.11.26 PYTHON_VERSION=3.12 RUST_VERSION=1 docker compose build ``` Compose sets `WORKSPACE_ROOT=/workspace` and mounts: - `./data/pi/agent:/home/node/.pi/agent` for Pi config/auth/sessions and pi-web metadata. - `./data/workspace:/workspace` in `compose.yml`. - `./:/workspace` in `compose.dev.yml`. ## Configuration Useful environment variables: - `HOST` / `PORT`: server bind host and port. CLI auto-falls back from 30141 only when PORT is not set. - `PI_WEB_CWD`: default workspace directory; falls back to `WORKSPACE_ROOT` then `process.cwd()`. - `PI_WEB_DATA_DIR`: pi-web metadata storage for checkpoints, tasks, bookmarks, MCP config, permissions, and evaluations; defaults to `$PI_CODING_AGENT_DIR/pi-web` or `~/.pi/agent/pi-web`. - `PI_WEB_CONFIG`: config JSON path override. - `PI_WEB_SHELL`: shell used by web terminals; defaults to `/bin/sh`. - `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`: provider keys for container/runtime use. ## Keyboard shortcuts - `Ctrl/⌘+N`: new session - `Ctrl/⌘+K`: focus prompt - `Ctrl/⌘+1` / `Ctrl/⌘+2`: switch to chat / terminal tab - `Ctrl/⌘+D`: open diff review - `Ctrl/⌘+Shift+T`: open validation - `Ctrl/⌘+.`: abort the running agent - `Ctrl/⌘+B`: toggle sidebar - `Ctrl/⌘+Enter`: send prompt from the composer - `Ctrl/⌘+Shift+L`: send recent terminal output to chat (terminal tab) - `?`: searchable shortcut/command help ## Troubleshooting Open Control room → Diagnostics to check Node.js, agent directory, API key hints, workspace write access, and shell setup. Usage/cost values are provider/SDK estimates and may show `0`/`—` when unavailable. ## Checks ```bash npm run lint # biome ci npm run ci # biome ci + typecheck + tests + build ```