Point it at a directory or repo, and pi-web loads your agent automatically—serving streaming chat, tools, attachments, and a Canvas surface as a production-ready front end, with virtually zero extra engineering.
Composing: distant peaks, the moon, negative space, in Ru-ware sky-blue…
Done—generated and placed it on the canvas to the right.The core is always pi. Whether it's your custom agent (via the SDK's runRpcMode) or the general pi --mode rpc, both speak the same RPC protocol. pi-web simply adds a web extension on top of that protocol—the bridge is fully reused, so pi's extensions, skills, and tools pass straight through.
# Point at any pi agent source to get a full site $ npx pi-web ./examples/aigc-agent ✓ Source resolved · detected index.ts → custom mode ✓ Session process ready ➜ http://localhost:3000
A single index.ts with a default-exported AgentDefinition—system prompt, custom tools, and model are all just fields. defineAgent() is there for type inference only, with no hard runtime dependency; omit the model and it inherits your pi login default.
import { defineAgent } from "@blksails/pi-web-agent-kit"; import { defineTool } from "@earendil-works/pi-coding-agent"; const echo = defineTool({ name: "echo", description: "Echo the text back.", async execute(_id, { text }) { return { content: [{ type: "text", text }] }; }, }); export default defineAgent({ // model omitted → inherits ~/.pi/agent default systemPrompt: "You are a helpful agent.", customTools: [echo], });
pi-web has already built the repetitive, expensive front-end work for you.
Images and files land in object storage and are served via signed URLs; base64 feeds vision LLMs, or hand files to server-side tools for processing.
Tools resolve files by attachmentId, execute, and persist their output back—results can be referenced again in the next turn. A full loop.
Images, reports, and web pages render as standalone canvases in the side panel—switch between code and preview, updating live as the conversation unfolds.
pi-web reuses pi's provider system—one provider is one source of models. Built-in providers like OpenAI, Anthropic, and Google connect out of the box; custom providers (such as Alibaba Cloud Bailian, DeepSeek and other regional services, or OpenAI-compatible gateways like NewAPI) just need a baseUrl and apiKey registered in ~/.pi/agent/models.json. Their models then show up in the settings page in a searchable dropdown, grouped by provider.
{
"providers": {
"my-gateway": {
"name": "My Gateway",
"baseUrl": "https://example.com/v1",
"apiKey": "sk-...",
"api": "openai-completions",
"models": [
{ "id": "some-model", "name": "Some Model" }
]
}
}
}
A language-agnostic HTTP/SSE protocol + one-way layered packages + a renderer registry. Decoupled layer by layer from protocol to component—run the full site, or drop the headless hooks into your own React stack.
import { PiChat } from "@blksails/pi-web-ui"; import { usePiSession } from "@blksails/pi-web-react"; export function App() { const session = usePiSession({ source: "./my-agent" }); return <PiChat session={session} />; }
The repo ships a pi-web dev skill — architecture map, command cheatsheet, and the non-obvious gotchas. Send the prompt on the right to Claude Code and it installs the skill into your project's local .claude/skills/ folder, auto-invoked whenever you work on pi-web.
Install the pi-web dev skill from github.com/blksails/pi-web: fetch .claude/skills/pi-web/SKILL.md from the repo into my project's .claude/skills/pi-web/SKILL.md. It auto-invokes when I work on pi-web.
The desktop app runs out of the box. The CLI turns any directory into a public-facing web app on the spot.
A native Tauri shell with a bundled Node runtime — nothing to install first, just download and run.
The installers are not code-signed yet, so the OS will stop you on first launch:
on macOS you'll see "cannot verify the developer" — open
System Settings › Privacy & Security and click "Open Anyway"; on Windows,
SmartScreen wants More info › Run anyway. The Linux AppImage needs
chmod +x first.
# Install globally npm i -g @blksails/pi-web # Point it at any agent directory pi-web ./my-agent # Or treat the current directory as the agent cd my-agent && pi-web
Requires Node >=22.19.0. The CLI ships the full frontend bundle and
server — no repo checkout needed. Use --port to change the port and
--watch to hot-reload when the agent changes.
Five minutes, from a directory to a public-facing, streaming web app.