pi-web: Instructions file for Codex

Pi Web - Development Notes

Quick Start

npm run dev   # port 30141

Typecheck: node_modules/.bin/tsc --noEmit · Lint: npm run lint

Never run next build during dev: it pollutes .next/ and breaks npm run dev.

Dev server troubleshooting

• First run lsof -nP -iTCP:30141 -sTCP:LISTEN and reuse a healthy Pi Web process. A second next dev on another port is no workaround: both contend for .next/dev/lock.
• A browser-only Module ... factory is not available overlay usually means that tab has a stale Turbopack/HMR graph, not a broken server or source. Use the browser's explicit reload, then compare the server log and a direct HTTP/API request.
• Restart only when the failure reproduces from a fresh page and the server-side checks fail too: stop that exact dev process gracefully, move .next into a mktemp -d backup, restart with npm run dev.
• Never fall back to next dev --webpack: the dev graph can fail on undici imports such as node:console. Development uses Turbopack.
• next dev may append a generated BEGIN:nextjs-agent-rules block to AGENTS.md. It is tooling output: check git status and keep it out of unrelated commits.

Upgrading pi

pi's packages up to 1.2.0 depend on each other with ^ ranges (1.3.0 pins them exactly), and the published pi-web's dependencies resolve afresh on install (no lockfile ships). Install every @earendil-works/* package the tree holds, the SDK's own dependencies included (pi-codemode, pi-mcp, pi-telemetry, …), with npm install --save-exact, so npm reuses those exact versions for the SDK's ranges. lib/pi-packages.test.mjs fails on any pi package that is not pinned that way; pi-web 0.12.0 pinned four, and installs after pi 1.2.0 paired pi-coding-agent 1.1.0 with pi-codemode 1.2.0.

---

Architecture

• Browsing (read-only, no AgentSession): GET /api/sessions lists ~/.pi/agent/sessions/; GET /api/sessions/[id] reads the .jsonl through SDK SessionManager helpers and lib/session-reader.ts, or an open wrapper's in-memory SessionManager. GET /api/agent/running snapshots the running ids.
• Sending: POST /api/agent/[id] → startRpcSession() (lib/rpc-manager.ts) creates the AgentSession in-process (createAgentSessionFromServices()); session.send(cmd) → session.prompt().
• Events: GET /api/agent/[id]/events streams SSE data: {...} from session.onEvent(), fed by session.subscribe().
• Product scope: a light web wrapper around pi, not an IDE or a platform of its own. Before adding a feature, check the out-of-scope list in CONTRIBUTING.md.
• Extension compatibility (principle): extensions written for the pi CLI must behave the same here. Fix display problems in the web client; never add pi-web-only options or fields to the extension API (ctx.ui.* options, extension_ui_request). pi's TUI (node_modules/@earendil-works/pi-tui) is the reference for what an extension asking for something means.