Pi-web Directory Structure: Complete Guide to the Next.js TypeScript Layout

Pi-web organizes its codebase into five primary directories—app/, components/, lib/, docs/, and bin/—following standard Next.js conventions with TypeScript throughout.

Pi-web is a Next.js application that separates frontend UI, backend API logic, and core libraries into distinct, clearly defined folders. Understanding the Pi-web directory structure is essential for navigating the agent-client functionality, extending the chat interface, or contributing to the worktree management features. The repository maintains a flat hierarchy where test files co-locate with their source modules, and all business logic lives in the lib/ folder consumed by both server and client code.

Top-Level Directory Overview

The repository root contains standard configuration files alongside five functional directories that handle specific architectural concerns:

• app/ – Next.js pages, root layout, global styles, and the entry point component
• components/ – Reusable React UI pieces including chat windows, sidebars, and file explorers
• lib/ – Core TypeScript libraries powering server-side operations like agent communication and file access
• docs/ – Markdown documentation, release notes, and technical guides
• bin/ – Small CLI utilities for development workflows and worktree management

Configuration files at the root include package.json, tsconfig.json, next.config.ts, tailwind.config.ts, and ESLint configurations. Test files use the .test.mjs extension and sit alongside the modules they validate, such as lib/file-access.test.mjs adjacent to lib/file-access.ts.

Frontend Architecture: The app/ and components/ Directories

Next.js Pages and Layouts in app/

The app/ directory contains the Next.js App Router structure. The file app/page.tsx serves as the root page component and entry point for the UI, while app/layout.tsx provides the global shell that wraps all pages. Global CSS variables and Tailwind directives live in app/globals.css, and static assets like favicon.ico reside here as well.

Reusable React Components in components/

The components/ folder houses all React UI elements that render the chat interface and file management views. Key files include:

• components/ChatWindow.tsx – Core chat interface handling streaming responses and server-sent events
• components/SessionSidebar.tsx – Displays the session tree and file explorer navigation
• components/FileExplorer.tsx – Renders the repository file tree and worktree browser
• components/AppShell.tsx – Provides the main application layout container
• components/ChatInput.tsx and components/MarkdownBody.tsx – Handle user input and message rendering

Backend Logic and Core Libraries in lib/

The lib/ directory contains the server-side TypeScript modules that power Pi-web's agent communication and file system operations. These modules are imported by API routes in app/api/ and by client-side hooks.

Agent Client and Session Management

The lib/agent-client.ts file exports createAgentClient(), a typed wrapper around the /api/agent/* endpoints that manages communication with running sessions. For session lifecycle and object reuse, lib/rpc-manager.ts handles creation, pooling, and cleanup of AgentSession objects, ensuring efficient resource utilization.

File System and Worktree Handling

Security-checked file operations live in lib/file-access.ts, which exports functions like readFileFromRoot() that restrict access to permitted roots including session working directories and worktree paths. Git worktree operations reside in lib/worktree.ts, providing logic for discovery, creation, and removal of worktrees. Utility functions for data normalization are located in lib/normalize.ts, and shared type definitions live in lib/pi-types.ts.

Documentation and CLI Utilities

Markdown Guides in docs/

The docs/ directory contains project documentation including release.md for version notes, worktrees.md for git worktree usage instructions, and i18n.md for internationalization guidelines. These files provide migration guidance and architectural decisions for contributors.

Development Scripts in bin/

The bin/ folder contains small Node.js CLI helpers used during development. The primary script bin/pi-web.js implements commands for worktree management, while bin/pi-web-options.js handles argument parsing and bin/node-version.js manages Node.js environment checks. These utilities are executed directly via Node, for example: node bin/pi-web.js worktree add --cwd /path/to/repo --branch feature-x.

Practical Code Examples

Accessing a Session via the Agent Client

import { createAgentClient } from '@/lib/agent-client';

// Example: fetch the current state of a running session
async function getSessionState(sessionId: string) {
  const client = createAgentClient(sessionId);
  const state = await client.getState();   // GET /api/agent/[id]
  return state;
}

Source: lib/agent-client.ts

Reading Files Through the Security Layer

import { readFileFromRoot } from '@/lib/file-access';

async function readUserFile(relativePath: string) {
  // Only allowed roots (session cwd, worktree roots, ~/pi-cwd-*) are permitted
  const content = await readFileFromRoot(relativePath);
  console.log(content);
}

Source: lib/file-access.ts

Rendering the Chat Interface

import ChatWindow from '@/components/ChatWindow';

export default function Page() {
  return (
    <div className="h-screen flex flex-col">
      <ChatWindow sessionId="1234-abcd" />
    </div>
  );
}

Source: components/ChatWindow.tsx

Managing Worktrees via CLI

node bin/pi-web.js worktree add --cwd /path/to/repo --branch feature-x

Implemented in: bin/pi-web.js

Summary

• Pi-web follows a standard Next.js TypeScript structure with clear separation between UI components (components/), page routing (app/), and business logic (lib/).
• The lib/ directory contains critical server-side modules including agent-client.ts for session communication and file-access.ts for secure file operations.
• All source code uses TypeScript (.ts or .tsx), while test files use the .test.mjs extension and co-locate with their source modules.
• Documentation lives in docs/, development CLI tools reside in bin/, and the root contains standard Next.js configuration files.
• Key entry points include app/page.tsx for the UI root and lib/agent-client.ts for backend agent interactions.

Frequently Asked Questions

What is the main entry point for Pi-web's user interface?

The main entry point is app/page.tsx, which renders the root page component and serves as the initial load point for the Next.js application. This file imports components like ChatWindow and SessionSidebar from the components/ directory to build the initial layout.

Where does Pi-web store its server-side business logic?

Server-side logic resides in the lib/ directory, specifically in files like agent-client.ts for agent communication, file-access.ts for secure file operations, and rpc-manager.ts for session lifecycle management. These modules are consumed by API routes and server-side rendering functions.

How are tests organized in the Pi-web repository?

Tests use the .test.mjs extension and sit alongside the modules they test rather than in a separate directory. For example, lib/file-access.test.mjs tests the functions exported by lib/file-access.ts, keeping related code physically close and making import paths simple to manage.

What directory contains Pi-web's command-line utilities?

CLI utilities and development scripts are located in the bin/ directory. The primary script bin/pi-web.js provides worktree management commands, while supporting files like pi-web-options.js handle configuration parsing for development workflows.

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