# How to Clone the agegr/pi-web Repository: Complete Setup and Architecture Guide

> Easily clone the agegr/pi-web repository. Follow our guide to install dependencies and launch the dev server for a seamless setup experience.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: how-to-guide
- Published: 2026-08-11

---

**Clone the agegr/pi-web repository with `git clone https://github.com/agegr/pi-web.git`, install dependencies with `npm install`, and start the dev server with `npm run dev` on port 30141.**

The **pi-web** repository is a Next.js-based UI for the pi coding agent. This guide covers cloning, local setup, and architectural navigation so you can understand how browser, server, and in-process agent sessions interact.

---

## Cloning and Installing agegr/pi-web

### Step 1: Clone the Repository

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

```

No special credentials or submodules are required. The repository contains standard npm packages managed via [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json).

### Step 2: Install Dependencies

```bash
npm install

```

This installs all runtime and development dependencies including Next.js, React, TypeScript, and the pi agent integration libraries.

### Step 3: Start the Development Server

```bash
npm run dev

```

Per the **Quick Start** section in the development notes, the dev server listens on **port 30141** (`127.0.0.1:30141`). Never run `next build` during development—it pollutes the `.next/` directory and breaks `npm run dev`.

For validation, use:

```bash
node_modules/.bin/tsc --noEmit   # Type checking

npm run lint                     # ESLint checks

```

---

## Core Architecture of pi-web

Understanding the **agegr/pi-web** architecture helps you navigate the codebase effectively. The system follows a three-layer design:

| Layer | Responsibility | Key Files |
|-------|--------------|-----------|
| **Browser** | React components, routing, UI state | `components/`, `hooks/`, [`app/layout.tsx`](https://github.com/agegr/pi-web/blob/main/app/layout.tsx) |
| **Next.js Server** | HTTP API routes, SSE streaming | `app/api/agent/[id]/route.ts`, `app/api/agent/[id]/events/route.ts` |
| **AgentSession (in-process)** | Wraps pi agent in same Node process | [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts), [`lib/agent-client.ts`](https://github.com/agegr/pi-web/blob/main/lib/agent-client.ts) |

Data flows: **Browser** → POST to API → **Next.js Server** creates/retrieves `AgentSessionWrapper` → streams events back via **SSE** to browser.

---

## Key Design Patterns in pi-web

### Session Lifecycle Management

In [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts), each session ID maps to one `AgentSessionWrapper` instance stored in `globalThis.__piSessions`. This global registry prevents duplicate sessions and enables proper cleanup on fork operations.

The **fork** operation (creating independent session branches) must immediately destroy the old wrapper to avoid stale state—a subtle trap documented in the architecture notes.

### Model Scope Resolution

The [`lib/model-scope.ts`](https://github.com/agegr/pi-web/blob/main/lib/model-scope.ts) module filters visible LLM models based on user-provided patterns. It resolves which models appear in the UI dropdown, supporting both exact matches and wildcard patterns.

### Git Worktree Handling

The [`lib/worktree.ts`](https://github.com/agegr/pi-web/blob/main/lib/worktree.ts) module discovers and manages Git worktrees. The sidebar groups sessions by repository regardless of which worktree they originated from, enabling seamless multi-branch workflows.

Sessions persist as **JSONL files** under `~/.pi/agent/sessions/`, read via [`lib/session-reader.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts).

---

## Running and Extending Sessions

### Typical Session Flow

1. **Browser** sends POST to `/api/agent/[id]` (handled in `app/api/agent/[id]/route.ts`)
2. **[`rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/rpc-manager.ts)** creates or reuses `AgentSessionWrapper`
3. Wrapper forwards prompt to pi agent process
4. Events stream back via `/api/agent/[id]/events` SSE endpoint
5. **[`hooks/useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts)** receives and reconciles state on the client

### Extending Functionality

| Extension Point | API Route | Implementation |
|-----------------|-----------|----------------|
| **Plugins** | [`app/api/plugins/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/plugins/route.ts) | [`lib/plugins.ts`](https://github.com/agegr/pi-web/blob/main/lib/plugins.ts) uses `DefaultPackageManager` |
| **Skills** | [`app/api/skills/install/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/skills/install/route.ts) | Community skill installation |
| **Models** | Model panel UI | [`lib/model-catalog.ts`](https://github.com/agegr/pi-web/blob/main/lib/model-catalog.ts), `lib/models-config-store.test.mjs` |

Example—adding a custom plugin:

```bash
npm install custom-pi-plugin
npm run dev   # Auto-detected via plugin manager

```

---

## Testing and Validation

The repository includes comprehensive test coverage:

```bash
npm test        # Runs *.test.mjs files (model-scope, file access, git detection)

```

Key test files:
- `lib/model-scope.test.mjs` — Model pattern matching
- `lib/file-access.test.mjs` — File system operations
- `lib/git-changes.test.mjs` — Git change detection

---

## Source File Reference

| File | Purpose | GitHub Link |
|------|---------|-------------|
| [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) | Session wrapper lifecycle, fork handling | [source](https://github.com/earendil-works/pi-web/blob/main/lib/rpc-manager.ts) |
| [`lib/agent-client.ts`](https://github.com/agegr/pi-web/blob/main/lib/agent-client.ts) | Typed client for agent API | [source](https://github.com/earendil-works/pi-web/blob/main/lib/agent-client.ts) |
| [`lib/model-scope.ts`](https://github.com/agegr/pi-web/blob/main/lib/model-scope.ts) | Model visibility filtering | [source](https://github.com/earendil-works/pi-web/blob/main/lib/model-scope.ts) |
| [`lib/worktree.ts`](https://github.com/agegr/pi-web/blob/main/lib/worktree.ts) | Git worktree discovery | [source](https://github.com/earendil-works/pi-web/blob/main/lib/worktree.ts) |
| `app/api/agent/[id]/route.ts` | Main agent API endpoint | [source](https://github.com/earendil-works/pi-web/blob/main/app/api/agent/%5Bid%5D/route.ts) |
| `app/api/agent/[id]/events/route.ts` | SSE event streaming | [source](https://github.com/earendil-works/pi-web/blob/main/app/api/agent/%5Bid%5D/events/route.ts) |
| [`hooks/useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts) | Client-side session state | [source](https://github.com/earendil-works/pi-web/blob/main/hooks/useAgentSession.ts) |
| [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md) | Architecture documentation | [source](https://github.com/earendil-works/pi-web/blob/main/AGENTS.md) |
| [`README.md`](https://github.com/agegr/pi-web/blob/main/README.md) | User documentation | [source](https://github.com/earendil-works/pi-web/blob/main/README.md) |

---

## Summary

- **Clone** with standard `git clone https://github.com/agegr/pi-web.git`
- **Install** via `npm install` and run `npm run dev` on port 30141
- **Architecture** follows Browser → Next.js Server → AgentSession pattern with `globalThis.__piSessions` registry
- **Key modules**: [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) (sessions), [`lib/model-scope.ts`](https://github.com/agegr/pi-web/blob/main/lib/model-scope.ts) (models), [`lib/worktree.ts`](https://github.com/agegr/pi-web/blob/main/lib/worktree.ts) (Git)
- **Extend** via plugin/skill APIs with automatic detection
- **Test** with `npm test` covering model, file, and Git operations

---

## Frequently Asked Questions

### What Node version is required for pi-web?

Node **22.19 or newer** is required. The development notes explicitly specify this version for compatibility with the pi agent's native modules and Next.js 15 features.

### Why does `next build` break my development setup?

Running `next build` during development pollutes the `.next/` directory with production artifacts that conflict with the dev server's hot-reloading mechanism. Always use `npm run dev` for local development and reserve `next build` for production deployments.

### How are agent sessions persisted across server restarts?

Sessions are stored as **JSONL files** in `~/.pi/agent/sessions/`. The `SessionManager` in [`lib/session-reader.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts) reads these files on startup, and the sidebar groups them by repository using [`lib/worktree.ts`](https://github.com/agegr/pi-web/blob/main/lib/worktree.ts) for Git-aware organization.

### Can I run multiple agent sessions simultaneously?

Yes. The `globalThis.__piSessions` registry in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) maintains separate `AgentSessionWrapper` instances per session ID. Each session operates independently, and the browser UI manages multiple concurrent SSE streams through [`hooks/useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts).