How to Build the agegr/pi-web Project: Complete Setup Guide

Build the agegr/pi-web project by installing Node.js 22.19.0 or newer, then either run npx @agegr/pi-web@latest for immediate execution or clone the repository and run npm install followed by npm run dev to start the development server on port 30141.

The agegr/pi-web repository provides a local web UI for the pi coding agent, implemented as a Next.js TypeScript application with a lightweight CLI wrapper. Understanding how to build this project requires familiarity with its dual architecture: a Next.js backend API layer and a React frontend that communicates via Server-Sent Events (SSE). This guide covers all installation methods, development workflows, and critical configuration options based on the actual source implementation.

Prerequisites

Before building agegr/pi-web, ensure your environment meets these requirements:

• Node.js 22.19.0 or newer: The package.json explicitly specifies this engine requirement, and core dependencies like Next.js 13 rely on the latest V8 engine features.
• Git: Required for repository cloning and worktree support utilized by the UI components.
• Local pi agent (pi-mono): The application reads session files from ~/.pi/agent/sessions/, so the pi coding agent must be installed and running on the same host to provide full functionality.

Installation Methods

You have three distinct approaches to build and run agegr/pi-web, depending on whether you need a stable release or a development environment.

Option 1: Quick Start with npx (No Installation)

Execute the latest published version without installing anything permanently:

npx @agegr/pi-web@latest

This command downloads the package from npm, starts the development server, and automatically opens your browser to http://127.0.0.1:30141.

Option 2: Global Installation

For frequent usage, install the package globally:

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

Then start the UI with the simple command:

pi-web

To remove the global installation later, run:

npm uninstall -g @agegr/pi-web

Option 3: Build from Source (Development)

For contributing or customizing the codebase, build directly from the GitHub repository:

1. Clone the repository:

git clone https://github.com/agegr/pi-web.git
cd pi-web

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

The hot-reload development server listens on http://127.0.0.1:30141 by default.

4. Verify the build integrity:

# Run the test suite

npm test

# Verify TypeScript typing without emitting files

node_modules/.bin/tsc --noEmit

# Lint the codebase

npm run lint

Critical Warning: Never invoke next build (or npm run build) while the development server is running. As documented in AGENTS.md, building writes to the .next/ directory and corrupts the hot-reload state, requiring a full restart.

Configuration and Runtime Options

The agegr/pi-web project supports extensive configuration via CLI flags and environment variables, parsed in bin/pi-web.js and passed to the Next.js runtime:

• --port <num> or PORT=<num>: Binds the HTTP server to a custom port (default: 30141).
• --hostname <addr> or PI_WEB_HOSTNAME=<addr>: Exposes the UI on network interfaces other than 127.0.0.1.
• --no-open or PI_WEB_NO_OPEN=1: Prevents automatic browser launching on startup.
• PI_WEB_PASSWORD='<secret>': Enables basic authentication (username is always pi) to secure all HTTP endpoints.
• PI_WEB_ALLOWED_HOSTS='host1,host2': Restricts accepted hostnames when running behind reverse proxies.
• HTTP_PROXY, HTTPS_PROXY, NO_PROXY: Routes server-side API calls through corporate proxies.

Combine options as needed, for example:

pi-web --port 8080 --hostname 0.0.0.0 --no-open

Project Architecture Overview

Understanding the build process requires familiarity with the project's bifurcated architecture separating API routes from UI components.

Next.js API Layer

The backend resides in /app/api/ and provides REST-like endpoints for:

• Session management (/api/sessions/*): Handled by utilities in lib/session-reader.ts that parse .jsonl session files and normalize tool calls.
• Agent communication (/api/agent/*): Implements SSE streams for real-time interaction with the pi agent.
• Worktree manipulation: Supports the pi agent's git worktree workflows as documented in docs/worktrees.md.

These handlers import from lib/ utilities, particularly lib/rpc-manager.ts, which maintains the AgentSessionWrapper registry, manages idle timeouts, and handles fork operations.

React Frontend Components

The user interface in components/ and hooks/ includes:

• AppShell.tsx: Manages layout and URL state persistence.
• SessionSidebar.tsx: Renders the project selector, session tree, and worktree switcher.
• ChatWindow.tsx: Displays real-time chat messages with streaming SSE events.
• hooks/useAgentSession.ts: Orchestrates the AgentSession lifecycle, managing prompt submissions, SSE reconnections, and idle-timeout cleanup via rpc-manager.ts.

Key Source Files

When building or debugging agegr/pi-web, reference these critical files:

• package.json: Defines Node.js 22.19.0 engine requirement, dependency tree, and npm scripts.
• AGENTS.md: Contains architecture diagrams, development notes, and the critical warning about concurrent build/dev processes.
• bin/pi-web.js: CLI entry point (#!/usr/bin/env node) that forwards commands to npm run dev or npm start.
• lib/rpc-manager.ts: Central registry for agent sessions and timeout management.
• lib/session-reader.ts: Parses session persistence files from the pi agent.
• hooks/useAgentSession.ts: Primary React hook driving chat interactions.
• components/ChatWindow.tsx: Main UI component for message rendering.

Summary

• agegr/pi-web requires Node.js 22.19.0+ and a local pi agent installation to function fully.
• Use npx @agegr/pi-web@latest for immediate execution without installation, or npm install -g @agegr/pi-web for permanent access.
• For development, clone the repository, run npm install and npm run dev to start the server on port 30141.
• Never run next build while the dev server is active to avoid corrupting the .next/ directory.
• Configure ports, hostnames, and authentication via CLI flags or environment variables parsed by bin/pi-web.js.
• The architecture splits between Next.js API routes (backend) and React components (frontend), communicating via SSE streams managed in lib/rpc-manager.ts.

Frequently Asked Questions

What Node.js version is required to build agegr/pi-web?

The package.json specifies Node.js 22.19.0 or newer as a strict engine requirement. This version ensures compatibility with Next.js 13 dependencies and the latest V8 engine features used by the streaming components.

Can I run pi-web without installing it globally?

Yes. Run npx @agegr/pi-web@latest to execute the package directly from npm without permanent installation. This downloads the latest version temporarily and starts the server immediately.

Why does the build fail when the development server is running?

According to AGENTS.md, running next build (or npm run build) concurrently with npm run dev corrupts the .next/ directory because both processes write to the same build output location. Always stop the dev server before building for production.

How do I secure the pi-web UI with authentication?

Set the PI_WEB_PASSWORD environment variable to enable basic HTTP authentication. The username is always pi, and all endpoints will require these credentials. For reverse proxy deployments, also configure PI_WEB_ALLOWED_HOSTS to prevent host header attacks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}