pi-web Product Documentation

简体中文 · This is the English edition; the Chinese edition lives in ../.

Put a production-ready Web UI on any agent written with the pi SDK in seconds.

This directory is the complete product documentation for pi-web, with each topic as a standalone document. The authoritative requirements and low-level design still live in the repo-root PLAN.md, .kiro/steering/, and the individual .kiro/specs/; this doc set targets users, integrators, agent authors, and contributors, providing a systematic, product-level walkthrough.

What is this

pi-web auto-loads a directory or git repository (containing an index.[js|ts] written with the @earendil-works/pi-coding-agent SDK) and brings up a streaming web chat UI. It can also serve the general-purpose pi coding agent as a web service, and is designed as the kernel + open layer for a future “pi cloud”.

Fastest start: at the repo root run pnpm install && pnpm dev, open http://localhost:3000 in your browser, and enter the absolute path of examples/hello-agent in the agent source picker to enter a session. For the full steps, see 01 · Quickstart.

Looking for a runnable example to get started? The repo’s examples/ directory provides a runnable example index organized by capability → examples index.

Documentation map

Pick a reading path by role:

I am…	Recommended order
First encounter (evaluating/trying out)	00 · Product Overview → 01 · Quickstart → 02 · Core Concepts
Agent author (want to put a UI on your own agent)	01 · Quickstart → 07 · Custom Agent Development → 08 · Attachment System → 21 · Sessions List → 10 · Web UI Extension → 11 · AIGC Tools
Integrator (embedding pi-web into your own stack)	03 · Architecture → 04 · Packages → 13 · HTTP/SSE API Reference → 21 · Sessions List → 12 · Config UI
Ops / Deployment	05 · Configuration → 14 · CLI → 15 · Deployment & Operations → 16 · Logging
Contributor	03 · Architecture → 04 · Packages → 17 · Development & Testing → 19 · Roadmap

All chapters

#	Document	One-liner
00	Product Overview	Positioning, capabilities, value, target scenarios
01	Quickstart	From a working environment to running your first agent
02	Core Concepts	Agent Source / dual-mode / Session / RPC / translation layer
03	Architecture	Data flow, transport-agnostic channel, stateful constraints, extension seams
04	Packages	Responsibilities and dependency direction of the 7 `@blksails/*` packages
05	Configuration	Environment variables, `~/.pi/agent`, hiding providers
06	Providers & Models	Built-in and custom OpenAI-compatible gateway integration
07	Custom Agent Development	`defineAgent()`, the `index.ts` contract, example index, hot reload
08	Attachment System	Layered storage, two consumption paths, `attachmentId` round-trip
09	Extensions / Skills / Templates	Native pi resources, permission prompts, install management
10	Web UI Extension	The agent-web-extension five-tier model
11	AIGC Image Tools	Generation/editing, default model, image normalization
12	Config UI	JSON Schema → form IR, dynamic widgets
13	HTTP/SSE API Reference	REST + SSE endpoint contracts
14	CLI	The `pi-web` global command, standalone, `--watch`
15	Deployment & Operations	standalone artifact, sticky routing, production hardening
16	Logging	Isomorphic logger, server-side gating
17	Development & Testing	TS strict, hard testing requirements, the spec workflow
18	Troubleshooting / FAQ	Common errors and remedies
19	Roadmap	Capability matrix and planning
20	Glossary	Definitions of key terms
21	Sessions List	Browse historical sessions and resume in one click

Conventions

This is the English edition; the Chinese edition lives in ../README.md. Technical terms and code identifiers are kept in their original form.
Code paths are written in path:line form for easy navigation within the repo.
This doc set does not reference the early, scattered design drafts under ./docs; content follows the README, steering, and the actual code.