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

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

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.

Step 2: Install Dependencies

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

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:

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
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, 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, 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 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 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.

---

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 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 receives and reconciles state on the client

Extending Functionality

Extension Point	API Route	Implementation
Plugins	app/api/plugins/route.ts	lib/plugins.ts uses DefaultPackageManager
Skills	app/api/skills/install/route.ts	Community skill installation
Models	Model panel UI	lib/model-catalog.ts, lib/models-config-store.test.mjs

Example—adding a custom plugin:

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

---

Testing and Validation

The repository includes comprehensive test coverage:

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	Session wrapper lifecycle, fork handling	source
lib/agent-client.ts	Typed client for agent API	source
lib/model-scope.ts	Model visibility filtering	source
lib/worktree.ts	Git worktree discovery	source
app/api/agent/[id]/route.ts	Main agent API endpoint	source
app/api/agent/[id]/events/route.ts	SSE event streaming	source
hooks/useAgentSession.ts	Client-side session state	source
AGENTS.md	Architecture documentation	source
README.md	User documentation	source

---

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 (sessions), lib/model-scope.ts (models), 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 reads these files on startup, and the sidebar groups them by repository using lib/worktree.ts for Git-aware organization.

Can I run multiple agent sessions simultaneously?

Yes. The globalThis.__piSessions registry in 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.

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