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

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 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. 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 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 for main layout management, FileExplorer.tsx for sidebar navigation, and 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, 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. 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 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:

npx @agegr/pi-web@latest

Or install globally for persistent access:

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:

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:

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:

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 and interactive chat through 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, 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 for layout, FileExplorer.tsx for navigation, and 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.

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