# What Is the Pi-Web Repository? A Local Web UI for the Pi Coding Agent

> Discover the pi-web repository a local web UI for the Pi coding agent. Browse sessions chat in real-time and manage agent settings with this Next.js application.

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

---

**The pi-web repository provides a local web interface for the Pi coding agent, enabling developers to browse historical sessions, engage in real-time chat with structured tool calls, and manage agent configuration through a Next.js-based browser application.**

The pi-web repository is an open-source project that transforms terminal-based Pi agent interactions into a rich browser experience. It reads session files from `~/.pi/agent/sessions/` and exposes a comprehensive workspace where developers can explore past conversations, execute new commands, and configure models without leaving their web browser.

## Core Purpose and Capabilities

The pi-web repository serves as a **local web UI for the Pi coding agent**, bridging command-line functionality with visual interfaces. It provides read-only access to historical session data and interactive capabilities for live agent communication.

### Session Management and Browsing

The application reads `.jsonl` session files directly from the Pi data directory, allowing developers to **browse and explore past Pi sessions** without navigating terminal history or file paths. The [`lib/session-reader.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts) module parses these files and builds branch contexts for navigating complex conversation trees. This functionality is exposed through API routes under `app/api/sessions/*`, providing structured access to session metadata and message history.

### Real-Time Agent Interaction

For interactive workflows, pi-web creates **in-process AgentSession instances** managed by [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts). These sessions handle message streaming, tool calls, and lifecycle management while surviving Next.js hot-reloads through a global registry (`globalThis.__piSessions`). The system enforces an **idle timeout of 10 minutes** to prevent resource leaks, automatically cleaning up inactive sessions.

### Configuration and Plugin Management

The interface includes dedicated panels for **model configuration** and **skill management**. It reads and writes [`models.json`](https://github.com/agegr/pi-web/blob/main/models.json) to handle OAuth and API-key flows, while exposing endpoints at `/api/skills/*` and `/api/plugins/*` to install, enable, or disable agent capabilities without terminal commands.

## Architecture Overview

The pi-web repository implements a three-layer architecture that separates presentation, API routing, and agent process management.

**Browser Layer**: The frontend is built with Next.js and React, providing components like [`AppShell.tsx`](https://github.com/agegr/pi-web/blob/main/AppShell.tsx) for main layout management, [`FileExplorer.tsx`](https://github.com/agegr/pi-web/blob/main/FileExplorer.tsx) for sidebar navigation, and [`ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/ChatWindow.tsx) for rendering Markdown-formatted responses and tool results.

**Next.js Server Layer**: API routes under `app/api/…` handle HTTP requests and Server-Sent Events (SSE). Key endpoints include `/api/agent/[id]` for session commands, `/api/sessions` for historical data, and `/api/models` for configuration management. These routes either read session files directly or proxy commands to active AgentSessions.

**AgentSession Layer**: Created by [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts), these wrappers encapsulate Pi `AgentSession` objects, managing message streaming and tool execution. This layer maintains the connection between the web interface and the underlying Pi agent process.

## Key Features and File Structure

### Session Forking and Branching

The system supports both **forking** (creating new `.jsonl` files) and **in-session branching** (navigating within existing files) through the API architecture described in [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md). This allows developers to explore alternative conversation paths without losing original context.

### Git Worktree Integration

Through endpoints at `/api/worktrees/*`, pi-web enables **switching Git worktrees** directly from the UI. When developers switch branches, the system creates worktrees under `<repoRoot>-worktrees/<branch-name>` and updates the file explorer sidebar accordingly, ensuring new sessions follow the selected branch context.

### File Preview and Exploration

The [`components/FileExplorer.tsx`](https://github.com/agegr/pi-web/blob/main/components/FileExplorer.tsx) module provides a **side-by-side file preview** system supporting source code, images, and PDFs. This integrates with the chat interface to allow referencing project files during agent conversations.

### Security and Authentication

Optional **HTTP Basic Auth** protects all endpoints when the `PI_WEB_PASSWORD` environment variable is set, securing local agent access in shared development environments.

## Installation and Usage Examples

### Starting the Development Server

Run pi-web without installation using npx:

```bash
npx @agegr/pi-web@latest

```

Or install globally for persistent access:

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

```

The server starts on `127.0.0.1:30141` and automatically opens the browser.

### Creating a New Agent Session

Create interactive sessions via the REST API:

```bash
curl -X POST http://127.0.0.1:30141/api/agent/new \
  -H "Content-Type: application/json" \
  -d '{
        "cwd": "/home/user/project",
        "message": "Explain the repository structure",
        "toolNames": ["file-explorer"]
      }'

```

This returns a session ID for subsequent commands.

### Streaming Chat Messages

Send messages to existing sessions and receive SSE responses:

```bash
curl -X POST http://127.0.0.1:30141/api/agent/<SESSION_ID> \
  -H "Content-Type: application/json" \
  -d '{"command":"prompt","input":"What does the lib/rpc-manager.ts module do?"}'

```

The response streams events containing the assistant's reply and tool results.

### Managing Git Worktrees

Switch to a feature branch worktree programmatically:

```bash
curl -X POST http://127.0.0.1:30141/api/worktrees \
  -H "Content-Type: application/json" \
  -d '{"branch":"feature-xyz"}'

```

This creates `<repoRoot>-worktrees/feature-xyz` and updates the UI context.

## Summary

- The pi-web repository is a **Next.js application** providing a browser-based interface for the Pi coding agent.
- It supports **read-only session browsing** via [`lib/session-reader.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts) and **interactive chat** through [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts).
- The architecture uses **API routes** under `app/api/` to expose session management, model configuration, and plugin control.
- **Git worktree integration** allows branch switching without leaving the browser interface.
- Sessions persist across hot-reloads using `globalThis.__piSessions` with automatic cleanup after 10 minutes of inactivity.

## Frequently Asked Questions

### What is the pi-web repository used for?

The pi-web repository provides a local web interface for interacting with the Pi coding agent. It allows developers to browse historical agent sessions stored in `~/.pi/agent/sessions/`, engage in real-time chat with structured tool calls, and manage agent configuration including models and plugins through a visual interface rather than command-line tools.

### How does pi-web handle agent sessions?

The system manages sessions through [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts), which creates in-process AgentSession wrappers that handle message streaming and tool execution. Active sessions are stored in a global registry (`globalThis.__piSessions`) to survive Next.js hot-reloads, with an enforced idle timeout of 10 minutes to prevent resource exhaustion.

### What technology stack does pi-web use?

Pi-web is built on **Next.js** with React components including [`AppShell.tsx`](https://github.com/agegr/pi-web/blob/main/AppShell.tsx) for layout, [`FileExplorer.tsx`](https://github.com/agegr/pi-web/blob/main/FileExplorer.tsx) for navigation, and [`ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/ChatWindow.tsx) for conversation display. It uses Server-Sent Events (SSE) for real-time communication and exposes REST APIs under `app/api/` for session and configuration management.

### How does pi-web integrate with Git worktrees?

The repository provides API endpoints at `/api/worktrees/*` that enable creating and switching between Git worktrees directly from the browser. When switching branches, the system creates isolated worktrees under `<repoRoot>-worktrees/<branch-name>` and updates the file explorer component to reflect the new working directory context.