@pananfly/pi-web

Pi Web

中文文档

Local web UI for the pi coding agent. Pi Web reads your local pi session files and gives you a browser workspace for session browsing, real-time chat, model configuration, skill management, and project file preview.

The same pi session in CLI and Pi Web: structured tool calls, readable Markdown, session browsing, and cleaner results.

Quick Start

Run without installing:

npx @agegr/pi-web@latest

Or install globally:

npm install -g @agegr/pi-web
pi-web

Then open http://localhost:30141. The CLI will try to open the browser automatically after the server is ready.

Options:

pi-web --port 8080              # custom port
pi-web --hostname 127.0.0.1     # local access only
pi-web -p 8080 -H 127.0.0.1     # combine options
pi-web --no-open                # do not open the browser automatically

PORT=8080 pi-web                # environment variable is also supported
PI_WEB_NO_OPEN=1 pi-web         # useful when running as a background service

HTTP Proxy

Pi Web reads the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables for server-side model and API requests.

On macOS or Linux:

HTTP_PROXY=http://127.0.0.1:7890 \
HTTPS_PROXY=http://127.0.0.1:7890 \
NO_PROXY=localhost,127.0.0.1 \
npx @agegr/pi-web@latest

On Windows PowerShell:

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:NO_PROXY = "localhost,127.0.0.1"
npx @agegr/pi-web@latest

Features

• Pick work back up: browse previous pi conversations by project without digging through terminal history or session paths.
• Try different directions safely: continue from an earlier message or fork a session into a separate route.
• Work across branches: switch Git worktrees from the sidebar so new sessions and the Explorer follow the checkout you choose.
• Chat beside the project: browse files on the left and preview source, docs, images, audio, and PDFs on the right while the agent works.
• See session state clearly: context usage, cost, compaction state, and system prompt details are visible from the top bar.
• Configure less from the terminal: manage models, login/API keys, model tests, and skill switches from the web UI.

Notes

• Data directory: Pi Web reads ~/.pi/agent/sessions by default. Set PI_CODING_AGENT_DIR to point at another pi agent directory.
• Session files: files are stored as ~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl.
• Model config: the Models panel reads and writes models.json in the pi agent directory. Model lists and defaults come from pi's config.
• File access: file browsing and preview are scoped to the selected project directory and working directories that appear in sessions.
• Git worktrees: see Worktrees in Pi Web for when the switcher appears, how new worktrees are created, and what removal does.
• Forks vs in-session branches: Fork creates a new .jsonl file. "Edit from here" creates another branch inside the same session file.

Development

npm install
npm run dev

The local dev server runs at http://localhost:30141.

Common checks:

node_modules/.bin/tsc --noEmit
npm run lint

Avoid running next build / npm run build during local development. It writes to .next/ and can interfere with the dev server; leave builds for release work.

Project Structure

app/
  api/
    agent/          # creates/drives AgentSession and exposes SSE events
    auth/           # OAuth and API key management
    cwd/validate/   # custom working directory validation
    default-cwd/    # pi default working directory lookup
    files/          # file listing, reading, preview, and watching
    home/           # current user home directory
    models/         # available models, default model, thinking levels
    models-config/  # read/write models.json and test models
    sessions/       # session reads, rename, delete, context, HTML export
    skills/         # skill listing, search, install, enable/disable
components/
  AppShell.tsx        # main layout, URL state, top panels, file tabs
  SessionSidebar.tsx  # project selector, session tree, Explorer
  ChatWindow.tsx      # messages, SSE, image drag/drop, minimap
  ChatInput.tsx       # input bar, model/tools/thinking/compact/slash controls
  MessageView.tsx     # message, thinking, tool call/result rendering
  ModelsConfig.tsx    # model and auth configuration panel
  SkillsConfig.tsx    # skill management panel
  FileExplorer.tsx    # file tree
  FileViewer.tsx      # source, diff, image, audio, PDF, DOCX preview
lib/
  http-dispatcher.ts  # HTTP(S) proxy setup for server-side fetch
  rpc-manager.ts      # AgentSessionWrapper lifecycle and global registry
  session-reader.ts   # parses .jsonl session files and branch contexts
  normalize.ts        # normalizes toolCall field names
  file-access.ts      # file read safety boundary
  file-paths.ts       # path encoding and relative path helpers
  markdown.ts         # Markdown/Mermaid/KaTeX plugin configuration
  pi-types.ts         # pi-related types
hooks/
  useAgentSession.ts  # session loading, command sending, SSE state machine
  useAudio.ts         # completion sound
  useDragDrop.ts      # image drag/drop
  useTheme.ts         # theme switching
bin/
  pi-web.js           # npm CLI entrypoint
instrumentation.ts    # initializes the server HTTP dispatcher