# Technologies Used in the agegr/pi-web Project: A Complete Stack Breakdown

> Explore the agegr/pi-web project stack: Nextjs React Tailwind CSS and markdown libraries. Get a full breakdown of the technologies powering this advanced application.

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

---

**The agegr/pi-web project is a full-stack TypeScript application built on Next.js v16 and React 19, utilizing Tailwind CSS v4 for styling and a specialized set of markdown processing libraries to render AI agent interactions.**

The **agegr/pi-web** repository powers Pi Web, a browser-based interface for the *pi* coding agent. This modern web UI combines server-side rendering capabilities with rich client-side interactions to manage Git work-trees, render technical diagrams, and stream real-time agent responses. Understanding the technology stack behind agegr/pi-web reveals how it bridges the gap between a local AI coding agent and a polished web interface.

## Core Framework and Language Stack

The foundation of agegr/pi-web rests on a carefully selected trio of core technologies that provide type safety, server capabilities, and component-based architecture.

**Next.js v16** serves as the primary framework, configured in [`next.config.ts`](https://github.com/agegr/pi-web/blob/main/next.config.ts) to handle server-side rendering, API routes, and Server-Sent Events (SSE) streams. This version provides the full-stack environment necessary for proxying model endpoints and serving static files.

**TypeScript** targets ES2017 across the entire codebase, as defined in [`tsconfig.json`](https://github.com/agegr/pi-web/blob/main/tsconfig.json). This ensures static typing from the API layer through to the React components, catching errors at compile time rather than runtime.

**React 19** (specifically versions `^19.2.4` for both react and react-dom) powers the component model. All UI pieces—from `AppShell` to `ChatWindow`—are implemented as functional React components utilizing modern hooks.

## UI Styling and Design System

For styling, agegr/pi-web adopts a utility-first approach that enables rapid responsive design without leaving the TypeScript ecosystem.

**Tailwind CSS v4** works alongside PostCSS to provide utility-first styling, responsive design breakpoints, and CSS variables defined in [`app/globals.css`](https://github.com/agegr/pi-web/blob/main/app/globals.css). The configuration in [`tailwind.config.ts`](https://github.com/agegr/pi-web/blob/main/tailwind.config.ts) establishes the design tokens used throughout the interface.

The styling pipeline processes through PostCSS, ensuring that final CSS bundles are optimized for production while maintaining developer ergonomics during the build process.

## Content Rendering and Diagramming

A key differentiator in agegr/pi-web is its sophisticated markdown processing pipeline, enabling rich technical documentation within chat interfaces.

The project employs `react-markdown` augmented with several **unified ecosystem plugins**:
- `remark-gfm` for GitHub-flavored markdown (tables, strikethrough, task lists)
- `remark-math` for math syntax parsing
- `rehype-katex` for server-side math rendering
- `rehype-raw` and `rehype-sanitize` for safe HTML insertion

**Mermaid v11** and **KaTeX v0.16** handle visual elements. Mermaid renders flowcharts and sequence diagrams within agent responses, while KaTeX displays mathematical notation. This combination is implemented in [`components/MarkdownBody.tsx`](https://github.com/agegr/pi-web/blob/main/components/MarkdownBody.tsx) and configured in [`lib/markdown.ts`](https://github.com/agegr/pi-web/blob/main/lib/markdown.ts).

## Agent Integration and Communication Layer

The interface communicates with the local *pi* coding agent through a specialized SDK and robust HTTP handling.

The **@earendil-works** family of packages (all at v0.84) provides the core agent functionality:
- `@earendil-works/pi-agent-core` for low-level session management
- `@earendil-works/pi-ai` for model selection and inference
- `@earendil-works/pi-coding-agent` for tool handling
- `@earendil-works/pi-tui` for terminal UI-style interactions

**Undici v8** handles server-side HTTP(S) proxying to model endpoints, configured in the Next.js API routes to forward requests securely.

Utility libraries `js-yaml` and `proper-lockfile` manage configuration parsing and prevent race conditions when writing session data.

## Architecture and Data Flow

Agegr/pi-web implements a three-tier architecture clearly documented in [`AGENTS.md`](https://github.com/agegr/pi-web/blob/main/AGENTS.md). The data flow follows this pattern:

1. The browser communicates with Next.js API routes (`/api/sessions`, `/api/agent/[id]`)
2. The server creates or reuses an in-process `AgentSession` via [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts)
3. Session data persists as JSON-Lines files under `~/.pi/agent/sessions/`, parsed by [`lib/session-reader.ts`](https://github.com/agegr/pi-web/blob/main/lib/session-reader.ts)

The `useAgentSession` hook manages SSE streams, fork/branch logic, and state reconciliation between the server and UI components.

## Build Tooling and Runtime Requirements

The development environment enforces code quality through **ESLint** and **TypeScript** compilers, while the production build requires **Node.js ≥ 22.19** to guarantee modern language features and native ES-module support.

A custom service worker ([`public/sw.js`](https://github.com/agegr/pi-web/blob/main/public/sw.js)) enables Progressive Web App capabilities, caching static assets and providing offline fallback behavior for the agent interface.

## Code Examples

### Sending Commands to the Agent

The [`lib/agent-client.ts`](https://github.com/agegr/pi-web/blob/main/lib/agent-client.ts) file wraps the REST API to provide type-safe command submission:

```typescript
import { sendAgentCommand } from '@/lib/agent-client';

// Example: ask the agent to set a new model
await sendAgentCommand(sessionId, {
  set_model: { provider: 'anthropic', modelId: 'claude-sonnet-4-6' },
});

```

This function throws a typed `AgentCommandError` on failure and communicates with the `/api/agent/[id]` POST endpoint.

### Session Management in React Components

The root component coordinates session creation through React hooks:

```tsx
// Inside components/AppShell.tsx
const handleNewSession = useCallback((sessionId: string, cwd: string) => {
  // UI state updates omitted for brevity
  router.replace('/', { scroll: false });
}, [router]);

// Triggered by the "New Session" button
<button onClick={() => handleNewSession('tmp-123', '/home/user/project')}>
  New Session
</button>

```

### Rendering Rich Markdown Content

The markdown pipeline integrates Mermaid diagrams and mathematical notation:

```tsx
import ReactMarkdown from 'react-markdown';
import remarkGfm from 'remark-gfm';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';
import rehypeRaw from 'rehype-raw';
import rehypeSanitize from 'rehype-sanitize';
import { Mermaid } from '@/components/Mermaid';

const MarkdownBody = ({ source }: { source: string }) => (
  <ReactMarkdown
    remarkPlugins={[remarkGfm, remarkMath]}
    rehypePlugins={[rehypeRaw, rehypeSanitize, rehypeKatex]}
    components={{ mermaid: Mermaid }}
  >
    {source}
  </ReactMarkdown>
);

```

## Summary

- **agegr/pi-web** is built on **Next.js v16** with **React 19** and **TypeScript**, requiring **Node.js ≥ 22.19**.
- The UI uses **Tailwind CSS v4** for styling and a custom service worker for offline capability.
- Rich content rendering relies on `react-markdown` with plugins for **Mermaid v11** diagrams and **KaTeX v0.16** math.
- Agent communication flows through **Undici v8** and the **@earendil-works/pi-agent-core** SDK family.
- Session data is stored as JSON-Lines files and managed via the `AgentSession` class in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts).

## Frequently Asked Questions

### What version of Next.js does agegr/pi-web use?

Agegr/pi-web uses **Next.js v16**, configured in [`next.config.ts`](https://github.com/agegr/pi-web/blob/main/next.config.ts) to provide server-side rendering, API routes, and SSE stream handling. This version supports the modern React 19 features utilized throughout the codebase.

### How does agegr/pi-web render Mermaid diagrams in chat messages?

The project uses `react-markdown` with custom components in [`components/MarkdownBody.tsx`](https://github.com/agegr/pi-web/blob/main/components/MarkdownBody.tsx). It passes Mermaid syntax to a dedicated `Mermaid` component while processing the markdown through `remark-gfm` and `rehype-raw` plugins, enabling diagram rendering alongside standard markdown content.

### What is the minimum Node.js version required to run agegr/pi-web?

The project requires **Node.js ≥ 22.19**, as specified in [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json). This requirement ensures support for modern JavaScript features and native ES-modules that the pi-agent SDKs depend on.

### How does the UI communicate with the local pi coding agent?

Communication occurs through Next.js API routes that wrap the **@earendil-works/pi-agent-core** SDK. The `sendAgentCommand` function in [`lib/agent-client.ts`](https://github.com/agegr/pi-web/blob/main/lib/agent-client.ts) posts to `/api/agent/[id]`, which creates or reuses an `AgentSession` instance managed by [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) to handle the actual agent process communication.