git:20260903.c5c7f36 to git:20260930.2bf5c9c

- # PizzaPi — Agent Guide

-

- PizzaPi is a self-hosted web interface and relay server for the [`pi` coding agent](https://pi.dev/). It streams live agent sessions to any browser and allows remote interaction from mobile or desktop without needing terminal access.

-

- ---

-

- ## Repository Layout

-

- ```

- packages/

- cli/ CLI wrapper — launches pi with PizzaPi extensions and the runner daemon

- server/ Bun HTTP + WebSocket relay server (auth, session relay, attachments)

- ui/ React 19 PWA web interface (Vite, TailwindCSS v4, Radix UI / shadcn)

- tools/ Shared agent tools (bash, read-file, write-file, search, toolkit)

- docs/ Starlight (Astro) documentation site — https://pizzaface.github.io/PizzaPi/

- npm/ npm distribution — builds & publishes `npx pizzapi` packages

-

- docker/ Docker Compose (redis + server services)

- patches/ Bun patches for upstream pi packages (auto-applied on bun install)

- ```

-

- Build order: `tools` → `server` → `ui` → `cli`.

-

- ---

-

- ## Documentation Site

-

- User-facing documentation lives in `packages/docs/` — a [Starlight](https://starlight.astro.build/) (Astro) site deployed to GitHub Pages.

-

- - **Source**: `packages/docs/src/content/docs/` (`.mdx` files)

- - **Config**: `packages/docs/astro.config.mjs`

- - **Build**: `cd packages/docs && bun run build`

- - **Dev**: `cd packages/docs && bun run dev`

- - **Live site**: https://pizzaface.github.io/PizzaPi/

-

- **When changing CLI commands, flags, config options, or self-hosting behavior, always update the corresponding docs pages:**

-

- | Topic | Doc page |

- |-------|----------|

- | CLI commands & flags | `running/cli-reference.mdx` |

- | Config, env vars | `customization/configuration.mdx` |

- | MCP servers | `customization/mcp-servers.mdx` |

- | Hooks | `customization/hooks.mdx` |

- | Skills | `customization/skills.mdx` |

- | Agent definitions | `customization/agent-definitions.mdx` |

- | Claude plugins | `customization/claude-plugins.mdx` |

- | Provider services | `customization/providers.mdx` |

- | Subagents | `customization/subagents.mdx` |

- | `pizza web`, Docker | `deployment/self-hosting.mdx` |

- | Tailscale HTTPS | `deployment/tailscale.mdx` |

- | Runner daemon | `running/runner-daemon.mdx` |

- | Installation | `start-here/installation.mdx` |

- | Sandbox & safe mode | `security/sandbox.mdx` |

- | Architecture | `reference/architecture.mdx` |

- | Server env vars | `reference/environment-variables.mdx` |

-

- The README is intentionally slim — it has a quick start and links to the docs site. **Do not duplicate detailed docs in the README.**

-

- ---

-

- ## Tech Stack

-

- | Layer | Technology |

- |-------|------------|

- | Runtime / package manager | **Bun** (required — not Node/npm/yarn) |

- | Language | TypeScript (strict mode, ESM throughout) |

- | Server | Bun.serve, better-auth, Kysely + SQLite, Redis, web-push |

- | UI | React 19, Vite 6, TailwindCSS v4, Radix UI, shadcn/ui, streamdown |

- | Agent core | `@earendil-works/pi-coding-agent`, `@earendil-works/pi-ai`, `@earendil-works/pi-tui` |

-

- ---

-

- ## Common Commands

-

- ```bash

- # Install dependencies

- bun install

-

- # Build everything

- bun run build

-

- # Development (server + UI, hot-reload)

- bun run dev

-

- # Lint all packages

- bun run lint

-

- # Type-check all packages

- bun run typecheck

-

- # Run DB migrations

- bun run migrate

-

- # Clean all dist/ directories

- bun run clean

- ```

-

- ---

-

- ## Development Notes

-

- - **Always use `bun`** — no Node, npm, yarn, or pnpm.

- - **Build order**: `tools` must be built before `server` or `cli`; `ui` can be built in parallel with `server`.

- - **TypeScript**: run `bun run typecheck` to check all packages at once.

- - **Patches**: Never edit files inside `node_modules` directly — changes go in `patches/` and are applied via `bun install`.

- - **Turn/lifecycle semantics matter**: When changing tools, prompts, models, or other agent capabilities at runtime, verify exactly *when* the change becomes visible to the next assistant response. Do not assume a setter like `setActiveTools()` is immediate inside the current loop — add an integration test that crosses the boundary you are changing.

- - **Redis** is required for the server. For local dev without Docker: `redis-server` or `docker compose up redis`.

- - **Do not repoint sandbox/test harnesses at an existing user or production Redis instance** (for example `redis://127.0.0.1:6379`) without explicit user permission. Sandboxes must use their own isolated Redis and must not assume the user's local Redis is safe to reuse.

- - **Database migrations**: run `bun run migrate` after schema changes. DB file is `packages/server/auth.db`.

- - **UI + TUI for every feature**: Custom features should include both a **web UI** component (in `packages/ui`) and **TUI/CLI** support (agent tools in `packages/cli`). Backend-only features without a UI are incomplete — users interact through the web interface, not just agent tools. When adding a new capability, ask: "Can the user configure/see/use this from the web UI?" If not, add it.

-

- ---

-

- ## Upstream Patches

-

- PizzaPi patches four upstream pi packages via `patchedDependencies` in the root `package.json`. Patches live in `patches/` and are auto-applied on `bun install`. See `patches/README.md` for full details.

-

- ### @earendil-works/pi-agent-core

-

- - **Dynamic tool refresh:** When a tool changes the active tool set mid-run (for example Tool Deferral loading a deferred tool), the next assistant response now sees the refreshed tools/system prompt instead of the stale turn-start snapshot.

-

- ### @earendil-works/pi-coding-agent

-

- - **Version check removal:** Disables the npm registry version check and "Update Available" notification (irrelevant for PizzaPi's headless runner).

- - **Auth path display:** Shows the actual auth file path instead of hardcoded default.

-

- **Removed in Phase 1 (SessionHost):** the patch no longer copies session-control onto `ExtensionAPI` (`newSession`/`switchSession`/`fork`, `getQueuedMessages`/`replaceQueuedMessages`). Those were surface-widening — already native on `AgentSessionRuntime`/`AgentSession`. PizzaPi's remote extension now drives control through a host-owned `SessionHost` (`packages/cli/src/runner/session-host.ts`), threaded in via `extensions/remote/session-host-ref.ts`. `patches.test.ts` guards against the hunks silently returning on a version bump.

-

- **Removed in Phase 2 (SessionHost.sendUserMessage):** the `sendUserMessage({ expandPromptTemplates })` opt-in hunk (`dist/core/agent-session.js` + both `dist/core/extensions/types.d.ts` hunks) is gone too. `connection-handlers-factory.ts`'s `ConnectionHandlers.sendUserMessage` now calls `rctx.sessionHost.sendUserMessage()` directly instead of `(pi as any).sendUserMessage()`; `SessionHost.sendUserMessage` already drove `session.prompt({ expandPromptTemplates })` via pi's native (unpatched) `PromptOptions` field, so the patched ExtensionAPI wrapper had nothing left calling it.

-

- ### @earendil-works/pi-ai

-

- - **Anthropic web search:** Adds support for Anthropic's native server-side web search tool, including streaming handling and conversation round-tripping. Configured via `providerSettings.anthropic.webSearch` in `~/.pizzapi/config.json`. See `patches/README.md` for details.

-

- ### Recreating patches after a version bump

-

- 1. Update version specifiers in all `package.json` files

- 2. `bun install` to fetch the new versions

- 3. `bun patch @earendil-works/pi-coding-agent@<version>` — edit files, then `bun patch --commit 'node_modules/@earendil-works/pi-coding-agent'`

- 4. `bun patch @earendil-works/pi-ai@<version>` — edit files, then `bun patch --commit 'node_modules/@earendil-works/pi-ai'`

- 5. Run `cd packages/cli && bun test src/patches.test.ts` to verify

-

- ---

-

- ## Configuration Conventions

-

- - **Environment variable prefix:** PizzaPi-specific env vars use the `PIZZAPI_` prefix (e.g., `PIZZAPI_SERVER_URL`, `PIZZAPI_AUTH_TOKEN`). Upstream pi env vars use the `PI_` prefix (e.g., `PI_WEB_SEARCH`, `PI_CACHE_RETENTION`). Never introduce a new env var without one of these prefixes.

- - **MCP config format:** Always use the `mcpServers{}` format (Claude Code compatible) as the preferred format. The `mcp.servers[]` array format is supported but not preferred. Claude Code compatibility is always the priority.

-

- ---

-

- ## Docker & Deployment

-

- **Use `pizza web` to rebuild and redeploy the production server.** This is the preferred method — it rebuilds the Docker image from the repo source and restarts the production compose project at `~/.pizzapi/web/`. Runners and viewers reconnect automatically.

-

- ```bash

- # Preferred: rebuild + redeploy production server

- pizza web

- ```

-

- ---

-

- ## Testing

-

- **Test runner**: `bun test` (built-in Bun test runner). No additional frameworks needed.

- ```bash

- # Run all tests

- bun run test

- # Run tests for a specific package

- bun test packages/server

- bun test packages/tools

- bun test packages/ui

- cd packages/cli && bun test src/patches.test.ts

- ```

- ### Test file conventions

- - Co-locate test files next to the source: `foo.ts` → `foo.test.ts`

- - Integration / multi-module tests go in `packages/<pkg>/tests/`

- - Use `describe` / `test` / `expect` from `bun:test` — no extra imports needed

- ### Current coverage by package

- | Package | Test files | What's covered |

- |---------|-----------|----------------|

- | **server** | 11 | Validation, security, sessions store, attachments store, API routes, pruning, pi-compat, SIGTERM drain upgrade guard |

- | **ui** | 3 | Message grouping, session viewer utils, path utilities |

- | **tools** | 2 | Toolkit helpers, pi-compat |

- | **cli** | 1 | Patch application and runtime behavior |

- | **protocol** | 0 | ⚠️ Needs tests |

- | **npm** | 0 | Build/publish scripts — no runtime code |

- ### Testing standards

- - **All new code must include tests.** If you add or modify a module, add or update its `.test.ts` file.

- - **Run `bun run test` before committing.** Tests are part of the quality gates in session completion.

- - **Test pure logic first.** Validation, parsing, transforms, and utility functions should have thorough unit tests.

- - **Keep tests fast.** Avoid real network/Redis/DB calls in unit tests — mock or use in-memory alternatives.

- - **Test lifecycle boundaries explicitly.** If a bug depends on "next turn", "after tool call", startup sequencing, reloads, or streamed state, add a regression test that crosses that boundary. Snapshot/timing bugs are easy to miss with pure unit tests.

- ---

- ## Built-in System Prompt

- The CLI appends a built-in system prompt (`BUILTIN_SYSTEM_PROMPT` in `packages/cli/src/config.ts`) to every session automatically. It covers inter-agent communication, the subagent tool, and session completion guidance. User-configured `appendSystemPrompt` in `~/.pizzapi/config.json` is concatenated **after** the built-in, so custom additions stack on top.

- **When adding new tools or changing agent-facing behavior**, update `BUILTIN_SYSTEM_PROMPT` in `config.ts` — not config.json. This ensures all installs get the change without any setup step.

- ---

- ## Spawning Sub-Agents

- Spawned sessions are **automatically linked** — child events (questions, plans, completion) surface as trigger messages in the parent's conversation. No manual session ID plumbing needed.

- **Handling child triggers:**

- - Trigger messages arrive with a `<!-- trigger:ID -->` prefix and instructions — e.g. when the child calls AskUserQuestion or plan_mode, a trigger appears in your conversation.

- - Use `respond_to_trigger(triggerId, response)` to answer a child's question or approve a plan.

- - Use `escalate_trigger(triggerId)` to pass a trigger to the human viewer.

- - Use `tell_child(sessionId, message)` to proactively message a child session.

- - When the child finishes, a `session_complete` trigger arrives — acknowledge or follow up.

- **For non-linked sessions** (e.g., two sessions that weren't spawned by each other):

- - Use `send_message`/`wait_for_message` for manual inter-session messaging.

- - Include session IDs explicitly when coordinating.

- **Rules:**

- - The `subagent` tool handles its own communication — triggers only apply to `spawn_session`.

- - Sub-agents must follow the same coding standards (testing, typecheck, etc.) as the parent.

- ---

- ## Session Completion

- **When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.

- **MANDATORY WORKFLOW:**

- 1. **File issues for remaining work** - Create issues for anything that needs follow-up

- 2. **Update issue status** - Close finished work, update in-progress items

- 3. **Run quality gates** (if code changed) - Tests, linters, builds, typecheck — verify nothing is broken

- 4. **Commit all changes** - clear commit message describing what changed

- 5. **Push to remote** - This is MANDATORY:

- ```bash

- git pull --rebase

- git push

- git status # must show "up to date with origin"

- ```

- 6. **Clean up** - Clear stashes, prune remote branches

- 7. **Verify** - All changes committed AND pushed

- 8. **Hand off** — leave a clear summary of what was done and what's next

- **Rules:**

- - Work is NOT complete until `git push` succeeds

- - Never stop before pushing — that leaves work stranded locally

- - NEVER say "ready to push when you are" - YOU must push

- - If push fails, resolve and retry until it succeeds