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

> Easily build the agegr/pi-web project. Follow our guide to install Node.js and run the project via npx or by cloning the repo for development. Get started now.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: getting-started
- Published: 2026-08-09

---

**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`](https://github.com/agegr/pi-web/blob/main/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:

```bash
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:

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

```

Then start the UI with the simple command:

```bash
pi-web

```

To remove the global installation later, run:

```bash
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**:

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

```

2. **Install dependencies**:

```bash
npm install

```

3. **Start the development server**:

```bash
npm run dev

```

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

4. **Verify the build integrity**:

```bash

# 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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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:

```bash
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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/docs/worktrees.md).

These handlers import from `lib/` utilities, particularly [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/AppShell.tsx)**: Manages layout and URL state persistence.
- **[`SessionSidebar.tsx`](https://github.com/agegr/pi-web/blob/main/SessionSidebar.tsx)**: Renders the project selector, session tree, and worktree switcher.
- **[`ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/ChatWindow.tsx)**: Displays real-time chat messages with streaming SSE events.
- **[`hooks/useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts)**: Orchestrates the `AgentSession` lifecycle, managing prompt submissions, SSE reconnections, and idle-timeout cleanup via [`rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/rpc-manager.ts).

## Key Source Files

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

- **[`package.json`](https://github.com/agegr/pi-web/blob/main/package.json)**: Defines Node.js 22.19.0 engine requirement, dependency tree, and npm scripts.
- **[`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md)**: Contains architecture diagrams, development notes, and the critical warning about concurrent build/dev processes.
- **[`bin/pi-web.js`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts)**: Central registry for agent sessions and timeout management.
- **[`lib/session-reader.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts)**: Parses session persistence files from the pi agent.
- **[`hooks/useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts)**: Primary React hook driving chat interactions.
- **[`components/ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts).

## Frequently Asked Questions

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

The [`package.json`](https://github.com/agegr/pi-web/blob/main/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`](https://github.com/agegr/pi-web/blob/main/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.