How to Run the Development Server and Tests for Pi Web: A Complete Guide

Pi Web is a Next.js browser UI for the pi coding agent that you run locally using npm run dev and test with npm test.

This guide walks you through starting the development server and executing the test suite for Pi Web. The repository provides npm scripts that handle hot-reloading, type-checking, linting, and testing—all configured for rapid iteration on the browser interface.

Starting the Pi Web Development Server

Pi Web ships with two development server modes defined in package.json【https://github.com/agegr/pi-web/blob/main/package.json#L31-L33】.

Standard Local Development

The default dev script binds the Next.js server to 127.0.0.1:30141:

npm install     # one-time setup

npm run dev     # http://127.0.0.1:30141

The server watches source files and rebuilds automatically on change. This mode is restricted to localhost for security during development.

LAN Access Mode

For testing on other devices within your network, use the dev:lan script which binds to 0.0.0.0:

npm run dev:lan

This exposes the same port (30141) to your local network while maintaining hot-reload functionality.

Important: According to AGENTS.md【https://github.com/agegr/pi-web/blob/main/AGENTS.md】, never run next build during active development—the development server handles compilation on demand.

Running the Pi Web Test Suite

The test script executes Node's built-in test runner across all test files in the repository【https://github.com/agegr/pi-web/blob/main/package.json#L36-L38】:

npm test

This command:

• Discovers *.test.mjs files in app/, components/, hooks/, lib/, and public/
• Uses the experimental --strip-types flag to skip TypeScript declaration loading, improving execution speed
• Validates core logic including session handling, worktree management, and API routes

The test suite covers:

• Session management (app/ and lib/ modules)
• UI components (components/ React code)
• Client-side hooks (hooks/ like useAgentSession and useAudio)

Additional Development Commands

Type-Checking

Run the TypeScript compiler without emitting files (as documented in README.md【https://github.com/agegr/pi-web/blob/main/README.md#L21-L27】):

node_modules/.bin/tsc --noEmit

Linting

Execute ESLint via the configured npm script:

npm run lint

The linting configuration uses eslint-config-next as specified in package.json【https://github.com/agegr/pi-web/blob/main/package.json#L62-L64】.

Key Configuration Files

File	Purpose
package.json	Defines dev, dev:lan, test, and lint scripts【https://github.com/agegr/pi-web/blob/main/package.json】
README.md	Quick-start documentation and workflow notes【https://github.com/agegr/pi-web/blob/main/README.md】
AGENTS.md	Architecture overview and development server guidelines【https://github.com/agegr/pi-web/blob/main/AGENTS.md】

All commands assume execution from the repository root directory.

Summary

• Start developing: Run npm install once, then npm run dev for localhost or npm run dev:lan for network access
• Run tests: Execute npm test to validate all *.test.mjs files using Node's native test runner
• Quality checks: Use node_modules/.bin/tsc --noEmit for type-checking and npm run lint for code quality
• Port and host: Default is 127.0.0.1:30141; LAN mode uses 0.0.0.0:30141

Frequently Asked Questions

What port does the Pi Web development server use?

The development server runs on port 30141 for both npm run dev (localhost only) and npm run dev:lan (network accessible). This is hardcoded in the npm scripts within package.json【https://github.com/agegr/pi-web/blob/main/package.json#L31-L33】.

Why does npm test use the --strip-types flag?

The --strip-types experimental flag prevents Node from attempting to load TypeScript declaration files at runtime. This results in faster test execution while still allowing TypeScript syntax in your test files, as implemented in the test script【https://github.com/agegr/pi-web/blob/main/package.json#L36-L38】.

Can I run production builds during development?

No. According to AGENTS.md【https://github.com/agegr/pi-web/blob/main/AGENTS.md】, you should never run next build during active development. The development server (npm run dev) handles all compilation and hot-reloading automatically without requiring production builds.

Where are the test files located in the Pi Web repository?

Test files use the *.test.mjs naming convention and are distributed across app/, components/, hooks/, lib/, and public/ directories. The npm test command automatically discovers and executes all matching files.

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