# Dependencies for the agegr/pi-web Project: Complete Package Analysis

> Explore the agegr/pi-web project dependencies, including @earendil-works agents, Next.js 16.2.12, React 19, js-yaml, and proper-lockfile for efficient AI coding and file management.

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

---

**The agegr/pi-web project depends on four core `@earendil-works` agent packages (version 0.84.0), Next.js 16.2.12 with React 19, and utility libraries like `js-yaml` and `proper-lockfile` to manage AI coding sessions and file operations.**

The `agegr/pi-web` repository is a Next.js-based web interface for the pi coding agent. Understanding the dependencies for the agegr/pi-web project is essential for developers contributing to its AI-powered workflow or troubleshooting integration issues. This guide breaks down every runtime and development dependency listed in [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json), mapping each package to its specific architectural role within the codebase.

## Core Runtime Dependencies

The production dependencies in [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json) (lines 41-51) fall into three categories: the proprietary agent SDK, the web framework stack, and cross-platform utilities.

### Agent SDK Stack (@earendil-works/*)

Four packages from `@earendil-works` form the backbone of the pi ecosystem:

- **`@earendil-works/pi-agent-core` `0.84.0`** (line 41): Provides the RPC wrapper and session manager that communicates with the pi daemon.
- **`@earendil-works/pi-ai` `0.84.0`** (line 42): Handles high-level AI abstractions including model selection, thinking levels, and response streaming.
- **`@earendil-works/pi-coding-agent` `0.84.0`** (line 43): Implements the actual coding-assistant tools for file generation and manipulation.
- **`@earendil-works/pi-tui` `0.84.0`** (line 44): Supplies text-UI helpers reused by the web interface for consistent session formatting.

These packages are imported throughout the application, notably in [`app/api/agent/new/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/agent/new/route.ts) for session creation and [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) for RPC orchestration.

### Web Framework (Next.js & React)

The UI layer relies on modern React and Next.js versions:

- **`next` `16.2.12`** (line 46): Powers server-side rendering, API route handling (`/api/*`), and the hot-reload development server.
- **`react` `^19.2.4`** (line 48): Core UI component library.
- **`react-dom` `^19.2.4`** (line 49): DOM renderer for React components.

The entry point at [`bin/pi-web.js`](https://github.com/agegr/pi-web/blob/main/bin/pi-web.js) leverages these frameworks to launch the web UI, while [`next.config.ts`](https://github.com/agegr/pi-web/blob/main/next.config.ts) configures the build pipeline.

### Utility Libraries

Specialized utilities handle configuration parsing and system-level operations:

- **`js-yaml` `^5.2.3`** (line 45): Parses and stringifies YAML files for configuration and skill manifests.
- **`proper-lockfile` `4.1.2`** (line 47): Implements cross-platform file locking to prevent concurrent session writes.
- **`undici` `8.5.0`** (line 51): High-performance HTTP client used for server-side API calls to the pi daemon.
- **`remark-frontmatter` `^5.0.0`** (line 50): Parses YAML front-matter in Markdown files for the skill system.

## Development Dependencies

The `devDependencies` section includes tooling for type safety, styling, and markdown rendering:

- **TypeScript & Linting**: `typescript` `^5`, `eslint` `^9`, and `eslint-config-next` `16.2.12` enforce code quality.
- **Styling**: `tailwindcss` with `@tailwindcss/postcss` `^4.2.2` and `postcss` for CSS processing.
- **Markdown Rendering**: `react-markdown`, `react-syntax-highlighter`, `remark-gfm`, `remark-math`, `rehype-katex`, `rehype-raw`, and `rehype-sanitize` for safe markdown display with mathematical equations.
- **Icons**: `@lobehub/icons` `^5.6.0` for UI elements.
- **Document Processing**: `mammoth` `^1.12.0` for DOCX to HTML conversion and `mermaid` `^11.14.0` for diagram rendering.
- **Testing**: `jiti` `^2.7.0` as an ESM loader for test files across `app`, `components`, `hooks`, `lib`, and `public` directories.
- **Types**: `@types/*` packages for `js-yaml`, `node`, `proper-lockfile`, `react`, `react-dom`, and `react-syntax-highlighter`.

The project requires **Node.js `>=22.19.0`** as specified in the engines field.

## Architectural Roles of Key Dependencies

Understanding how these packages interact reveals the project's design patterns.

### Agent Session Management

The `@earendil-works` packages in [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) orchestrate RPC sessions and inject tool configurations. The `pi-agent-core` package supplies the session manager, while `pi-coding-agent` implements file operation tools used when processing code generation requests.

### File Operations and Concurrency

In [`lib/normalize.ts`](https://github.com/agegr/pi-web/blob/main/lib/normalize.ts), the codebase interacts with `@earendil-works/pi-agent-core` to normalize tool-call payloads. When writing session data, `proper-lockfile` guarantees exclusive access to `.jsonl` files, preventing race conditions when multiple agents manipulate the same session storage.

### Markdown and YAML Processing

The skill system relies heavily on `js-yaml` and `remark-frontmatter` to parse skill manifests. In [`components/ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/components/ChatWindow.tsx), the UI consumes these configurations and renders them using `react-markdown` with `remark-gfm` for GitHub-flavored syntax and `rehype-katex` for mathematical expressions.

## Practical Usage Examples

These snippets demonstrate how the dependencies are exercised in development workflows.

### Starting the Development Server

```bash
npm run dev

```

This command launches Next.js on localhost:30141, utilizing `next`, `react`, `react-dom`, `tailwindcss`, and `postcss`.

### Creating a New Pi Session via CLI

```bash
npx pi-web create --cwd ~/projects/example --model claude-sonnet-4-6

```

This invokes `@earendil-works/pi-agent-core`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-ai` to initialize a coding session.

### Reading YAML Skill Manifests

```typescript
import yaml from 'js-yaml';
import { readFileSync } from 'fs';

const manifest = yaml.load(readFileSync('skills/example/skill.yml', 'utf8'));
console.log(manifest);

```

This pattern appears throughout the skill loader logic, relying on `js-yaml` version `^5.2.3`.

### Rendering Markdown with Mathematics

```tsx
import ReactMarkdown from 'react-markdown';
import remarkGfm from 'remark-gfm';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export const MarkdownBody = ({ source }: { source: string }) => (
  <ReactMarkdown
    remarkPlugins={[remarkGfm, remarkMath]}
    rehypePlugins={[rehypeKatex]}
  >
    {source}
  </ReactMarkdown>
);

```

This component from [`components/ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/components/ChatWindow.tsx) demonstrates the markdown rendering pipeline using `react-markdown`, `remark-gfm`, `remark-math`, and `rehype-katex`.

### File Locking for Safe Writes

```typescript
import lockfile from 'proper-lockfile';
import { writeFileSync } from 'fs';

async function safeWrite(path: string, data: string) {
  const release = await lockfile.lock(path);
  try {
    writeFileSync(path, data);
  } finally {
    await release();
  }
}

```

This pattern utilizes `proper-lockfile` `4.1.2` to prevent corruption during concurrent session file updates.

### High-Performance HTTP Requests

```typescript
import { request } from 'undici';

async function pingDaemon() {
  const { statusCode, body } = await request('http://localhost:3000/api/agent/ping');
  const text = await body.text();
  console.log(statusCode, text);
}

```

The `undici` `8.5.0` client replaces native fetch for server-side calls to the pi daemon.

## Summary

- **Core Agent Stack**: Four `@earendil-works` packages (`pi-agent-core`, `pi-ai`, `pi-coding-agent`, `pi-tui`) at version `0.84.0` provide the AI coding functionality.
- **Web Foundation**: Next.js `16.2.12` and React `^19.2.4` power the server-rendered UI and API routes.
- **Data Handling**: `js-yaml` parses configurations, `proper-lockfile` prevents file corruption, and `undici` handles HTTP communication.
- **Development Tooling**: TypeScript `^5`, Tailwind CSS with PostCSS, ESLint `^9`, and extensive `@types/*` packages ensure type safety and code quality.
- **Node Requirement**: The project requires Node.js `>=22.19.0` as specified in [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json).

## Frequently Asked Questions

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

The project uses **Next.js `16.2.12`**, as specified in [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json) line 46 and mirrored in `eslint-config-next`. This version powers the server-side rendering, API endpoints, and development server on port 30141.

### Why does pi-web use proper-lockfile instead of native file locking?

**`proper-lockfile` `4.1.2`** provides cross-platform file locking that works consistently across Windows, macOS, and Linux. The codebase uses it to prevent race conditions when multiple agent processes write to the same session `.jsonl` files, ensuring data integrity during concurrent operations.

### What are the four core @earendil-works packages and their purposes?

The four proprietary packages are: **`@earendil-works/pi-agent-core`** (RPC and session management), **`@earendil-works/pi-ai`** (model selection and streaming), **`@earendil-works/pi-coding-agent`** (code generation tools), and **`@earendil-works/pi-tui`** (text UI helpers). All are locked to version `0.84.0` and imported in files like [`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts) and [`app/api/agent/new/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/agent/new/route.ts).

### Which Node.js version is required to run pi-web?

According to the engines field in [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json), the project requires **Node.js `>=22.19.0`**. This modern runtime is necessary for the ESM loader (`jiti`) and Next.js 16 features used throughout the codebase.