# How to Contribute to the agegr/pi-web Project: A Complete Developer's Guide

> Learn how to contribute to the agegr/pi-web project. This guide covers forking, local setup with Node.js 22+, Next.js architecture, and submitting tested pull requests following our workflow.

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

---

**Contributing to the agegr/pi-web project involves forking the repository, configuring a local Node.js 22+ development environment, understanding the Next.js architecture, and submitting a tested pull request that follows the established workflow.**

The agegr/pi-web repository is an open-source Next.js application that provides a web interface for the local pi coding agent. Whether you are fixing bugs, adding features, or improving documentation, understanding the core architecture and contribution workflow ensures your changes integrate seamlessly with the existing codebase.

## Understanding the Core Architecture

Before you contribute to the agegr/pi-web project, familiarize yourself with the layered architecture that separates server-side API handling from the React frontend.

### Server-Side API Layer

The backend logic resides in `app/api/`, where each folder groups related functionality. The `app/api/agent/[id]/route.ts` file handles session SSE (Server-Sent Events) and command processing, while [`app/api/models-config/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/models-config/route.ts) manages reading and writing the [`models.json`](https://github.com/agegr/pi-web/blob/main/models.json) configuration. These endpoints form the bridge between the UI and the underlying pi agent.

### Agent Session Management

Session lifecycle and state are centralized in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts). This module creates and tracks `AgentSessionWrapper` instances, ensuring a single wrapper per session ID and implementing idle-timeout cleanup. The global maps stored on `globalThis` survive Next.js hot-reloading, maintaining session continuity during development.

### Session File Parsing and Normalization

The [`lib/session-reader.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts) module parses `.jsonl` session files generated by the pi agent, converting them into UI-friendly structures. It handles tool-call normalization and branch navigation. The [`lib/normalize.ts`](https://github.com/agegr/pi-web/blob/main/lib/normalize.ts) utility translates raw tool-call objects into the shapes expected by the UI, functioning both during session loading and live event streaming.

### Worktree Integration

Git worktree switching is managed by [`lib/worktree.ts`](https://github.com/agegr/pi-web/blob/main/lib/worktree.ts), which resolves worktree paths, creates or removes worktrees, and enforces safety checks. This allows the UI to switch between different Git branches, ensuring new sessions follow the selected checkout.

### React Frontend Components

The UI layer in `components/` uses functional components that consume custom hooks. [`components/AppShell.tsx`](https://github.com/agegr/pi-web/blob/main/components/AppShell.tsx) manages layout and top-level state, [`components/SessionSidebar.tsx`](https://github.com/agegr/pi-web/blob/main/components/SessionSidebar.tsx) renders the project and session tree, and [`components/ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/components/ChatWindow.tsx) handles message streaming. Custom hooks like [`hooks/useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts) manage SSE state machines and command dispatch, while [`hooks/useAudio.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAudio.ts) handles completion sounds. Security-critical file system access is gated by [`lib/path-security.ts`](https://github.com/agegr/pi-web/blob/main/lib/path-security.ts) and [`lib/file-access.ts`](https://github.com/agegr/pi-web/blob/main/lib/file-access.ts), restricting reads to allowed roots including the session cwd, worktrees, and `~/pi-cwd-*` directories.

## Setting Up Your Development Environment

To contribute to the agegr/pi-web project, you must configure a local development environment that mirrors the production architecture.

1. **Fork and clone the repository**:

   ```bash
   git clone https://github.com/<your-username>/pi-web.git
   cd pi-web
   ```

2. **Install dependencies** (requires Node.js 22 or higher):

   ```bash
   npm install
   ```

3. **Start the development server**:

   ```bash
   npm run dev
   ```

   The application will be available at `http://127.0.0.1:30141` with hot-reloading enabled.

4. **Verify the setup** by running the full test suite:

   ```bash
   npm test
   node_modules/.bin/tsc --noEmit
   npm run lint
   ```

   All tests must pass before you submit any changes.

## Making and Submitting Contributions

Once your environment is configured, follow this workflow to ensure your contribution meets the project's quality standards.

Isolate your changes to a single logical concern. Create a new branch for your feature or bugfix:

```bash
git checkout -b <feature-or-bugfix>

```

When modifying code, maintain the existing patterns found in the source files. Add or update tests in the corresponding `*.test.mjs` files that live alongside implementation modules. This guarantees that hidden tests will pass during continuous integration.

Commit your changes with clear, descriptive messages. Do not push directly to the upstream `main` branch:

```bash
git add .
git commit -m "Brief description of change"

```

Push your branch to your fork and open a Pull Request on the original agegr/pi-web repository:

```bash
git push origin <feature-or-bugfix>

```

In your PR description, reference any related issues and summarize the architectural impact of your changes. Address reviewer feedback promptly, iterating until the maintainers approve the request.

## Common Contribution Patterns

These practical examples demonstrate how to extend specific areas of the codebase.

### Adding a New API Route

Create a file under `app/api/<resource>/route.ts` and export a standard Next.js handler:

```typescript
import { NextResponse } from 'next/server';

export async function GET() {
  return NextResponse.json({ status: 'ok' });
}

```

### Extending the Session Reader

To support a new custom entry type in [`lib/session-reader.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts), add a case within the `parseEntry` function:

```typescript
if (type === 'my_custom_type') {
  // Convert raw JSON to the internal shape and push to the context
}

```

### Updating the UI Components

To add interactive elements, modify the relevant component such as [`components/SessionSidebar.tsx`](https://github.com/agegr/pi-web/blob/main/components/SessionSidebar.tsx), using existing styling utilities from [`components/AppShell.tsx`](https://github.com/agegr/pi-web/blob/main/components/AppShell.tsx):

```tsx
<button onClick={handleMyAction}>My Action</button>

```

## Summary

- **agegr/pi-web** is a Next.js application providing a web UI for the pi coding agent, with clear separation between API routes, session management, and React components.
- Key architectural files include [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) for session lifecycle, [`lib/session-reader.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts) for parsing `.jsonl` files, and `app/api/` for server-side logic.
- Development requires Node.js 22+, uses port `30141` for local testing, and mandates running `npm test`, TypeScript checks, and linting before submission.
- Contributions must include tests in `*.test.mjs` files, follow the branching workflow, and maintain the security constraints enforced by [`lib/path-security.ts`](https://github.com/agegr/pi-web/blob/main/lib/path-security.ts).

## Frequently Asked Questions

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

The project requires Node.js 22 or higher. This version ensures compatibility with the modern Next.js features and dependency tree used in the pi-web codebase.

### How do I test my changes before submitting a PR?

Run the complete verification suite using `npm test`, followed by `node_modules/.bin/tsc --noEmit` for type checking and `npm run lint` for code style. Additionally, ensure all `*.test.mjs` files related to your changes pass successfully.

### Where is agent session state managed in the codebase?

Agent session state is managed in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts), which maintains `AgentSessionWrapper` instances in global maps on `globalThis`. This design ensures sessions survive Next.js hot-reloading while implementing proper idle-timeout cleanup.

### Can I add new API endpoints to the pi-web interface?

Yes, you can add new endpoints by creating a [`route.ts`](https://github.com/agegr/pi-web/blob/main/route.ts) file under the appropriate subdirectory in `app/api/`. Follow the existing pattern in `app/api/agent/[id]/route.ts` or [`app/api/models-config/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/models-config/route.ts), exporting standard Next.js request handlers that respect the path security constraints defined in [`lib/path-security.ts`](https://github.com/agegr/pi-web/blob/main/lib/path-security.ts).