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

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, mapping each package to its specific architectural role within the codebase.

Core Runtime Dependencies

The production dependencies in 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 for session creation and 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 leverages these frameworks to launch the web UI, while 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 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, 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, 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

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

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

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

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 demonstrates the markdown rendering pipeline using react-markdown, remark-gfm, remark-math, and rehype-katex.

File Locking for Safe Writes

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

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.

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 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 and app/api/agent/new/route.ts.

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

According to the engines field in 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.

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