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

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 manages reading and writing the 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. 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 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 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, 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 manages layout and top-level state, components/SessionSidebar.tsx renders the project and session tree, and components/ChatWindow.tsx handles message streaming. Custom hooks like hooks/useAgentSession.ts manage SSE state machines and command dispatch, while hooks/useAudio.ts handles completion sounds. Security-critical file system access is gated by lib/path-security.ts and 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:

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

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

   npm install

3. Start the development server:

   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:

   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:

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:

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:

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:

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, add a case within the parseEntry function:

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, using existing styling utilities from components/AppShell.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 for session lifecycle, 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.

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, 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 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, exporting standard Next.js request handlers that respect the path security constraints defined in lib/path-security.ts.

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