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

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 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. 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. The configuration in 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 and configured in 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. 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
3. Session data persists as JSON-Lines files under ~/.pi/agent/sessions/, parsed by 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) 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 file wraps the REST API to provide type-safe command submission:

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:

// 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:

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.

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 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. 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. 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 posts to /api/agent/[id], which creates or reuses an AgentSession instance managed by lib/rpc-manager.ts to handle the actual agent process communication.

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