Pi Web - Development Notes

August 9, 2026 · View on GitHub

Quick Start

npm run dev   # port 30141

Typecheck: node_modules/.bin/tsc --noEmit
Lint: npm run lint
Never run next build during dev — pollutes .next/ and breaks npm run dev.

Architecture

Browser                Next.js Server              AgentSession (in-process)
  │                        │                               │
  ├─ GET /api/sessions ────▶ reads ~/.pi/agent/sessions/   │
  ├─ GET /api/sessions/[id] reads .jsonl file directly     │
  ├─ GET /api/agent/running ───────▶ running id snapshot   │
  │                        │                               │
  ├─ send message ─────────▶ POST /api/agent/[id]          │
  │                        │   startRpcSession() ─────────▶│ createAgentSession()
  │                        │   session.send(cmd) ─────────▶│ session.prompt()
  │                        │                               │
  ├─ SSE connect ──────────▶ GET /api/agent/[id]/events    │
  │                        │   session.onEvent() ◀─────────│ session.subscribe()
  │◀── data: {...} ─────────│                               │

Session browsing (read-only): reads .jsonl files through SDK SessionManager helpers and lib/session-reader.ts — no AgentSession created.
Sending a message: startRpcSession() in lib/rpc-manager.ts creates an AgentSession in-process.

File Map

app/api/
  sessions/route.ts               GET  list all sessions
  sessions/[id]/route.ts          GET/PATCH/DELETE session
  sessions/[id]/context/route.ts  GET ?leafId= — context for a specific leaf
  sessions/[id]/export/route.ts   GET exported HTML for a session
  agent/new/route.ts              POST { cwd, message, toolNames?, provider?, modelId? }
  agent/[id]/route.ts             GET state | POST any command
  agent/[id]/events/route.ts      GET SSE stream
  agent/running/route.ts          GET currently-running session ids
  agent/running/events/route.ts   GET SSE stream of currently-running session ids
  auth/all-providers/route.ts     GET API-key provider list
  auth/api-key/[provider]/route.ts GET/POST/DELETE provider API key status/storage
  auth/login/[provider]/route.ts  GET OAuth/device-code SSE | POST manual code
  auth/logout/[provider]/route.ts POST OAuth logout
  auth/providers/route.ts         GET OAuth provider list
  cwd/validate/route.ts           POST validate/select a cwd
  default-cwd/route.ts            POST create ~/pi-cwd-YYYYMMDD
  files/[...path]/route.ts        GET file contents for viewer
  home/route.ts                   GET user home directory
  models/route.ts                 GET { models, modelList, defaultModel }
  models-config/route.ts          GET/PUT — read/write ~/.pi/agent/models.json
  models-config/catalog/route.ts  GET models.dev pricing presets
  models-config/discover/route.ts POST fetch a configured provider's upstream model list
  models-config/test/route.ts     POST test a configured model/provider
  plugins/route.ts                GET/POST package plugin management
  skills/route.ts                 GET/PATCH loaded skills and disable-model-invocation
  skills/install/route.ts         POST install skills through npx skills add
  skills/search/route.ts          GET/POST skills.sh search
  worktrees/route.ts              GET/POST/DELETE git worktrees

lib/
  agent-client.ts      typed fetch helper for /api/agent commands
  draft-store.ts       local draft persistence helpers
  file-access.ts       allowed file roots for /api/files and worktrees
  file-paths.ts        client/server path encoding helpers
  markdown.ts          shared markdown helpers
  npx.ts               npx runner used by skill install
  pi-types.ts          local structural types for pi SDK objects
  rpc-manager.ts      AgentSessionWrapper + registry + startRpcSession
  session-reader.ts   SessionManager wrappers + path cache + buildSessionContext adapter
  tool-presets.ts     PRESET_NONE/READ_ONLY/DEFAULT/FULL + getPresetFromTools()
  tool-preset-preference.ts  browser-persisted default for fresh sessions
  types.ts            shared TypeScript types
  normalize.ts        normalizeToolCalls() — field name mismatch between file format and our types
  worktree.ts         project/worktree resolution and git worktree operations

components/
  AppShell.tsx        layout + URL state + tab management
  SessionSidebar.tsx  session tree + FileExplorer
  ChatWindow.tsx      chat composition + completion sound wrapper
  ChatInput.tsx       input bar + model/thinking/tools/compact controls
  MessageView.tsx     renders one message (user/assistant/toolCall/toolResult)
  BranchNavigator.tsx in-session branch switcher
  ChatMinimap.tsx     scroll minimap alongside the message list
  MarkdownBody.tsx    markdown renderer
  ModelsConfig.tsx    modal for editing models.json (opened from sidebar bottom)
  PluginsConfig.tsx   modal for installed package plugins
  SkillsConfig.tsx    modal for loaded/search/installable skills
  FileExplorer.tsx    file tree inside sidebar
  FileIcons.tsx       file icon helpers
  FileViewer.tsx      file content in a tab
  TabBar.tsx          tab bar (Chat + open file tabs)

hooks/
  useAgentSession.ts  messages + streaming + SSE + fork/navigate/reconciliation logic
  useAudio.ts         completion sound + browser AudioContext unlock
  useDragDrop.ts      shared drag/drop state
  useIsMobile.ts      responsive breakpoint hook
  useTheme.ts         theme state

Key Design Decisions & Traps

AgentSession lifecycle (lib/rpc-manager.ts)

  • One AgentSessionWrapper per session id, keyed in globalThis.__piSessions
  • globalThis survives Next.js hot-reload; plain module-level Map does not
  • Idle timeout: 10 minutes. Concurrent startRpcSession() calls share a single start Promise (globalThis.__piStartLocks)

Fork must destroy the wrapper immediately

AgentSession.fork() mutates the wrapper's inner state in-place — after fork, inner.sessionId is the new session's id. If the wrapper stays alive in the registry under the old id, the next request gets the already-forked state and subsequent forks produce a corrupt parentSession chain.

Fix: send("fork") captures newSessionId, then calls this.destroy() before returning. The next request for the original session reloads a clean AgentSession from the original file.

Two kinds of branching — don't confuse them

  • Fork (Fork button on user message): creates a new independent .jsonl file. Shown as a child in the sidebar tree via parentSession header field.
  • In-session branch (Continue button / BranchNavigator): calls navigate_tree within the same file. Multiple entries share the same parentId. Switching between them calls /api/sessions/[id]/context?leafId=.

Session files can be fully rewritten

parentSession in the header is display metadata only — has zero effect on chat content. Safe to writeFileSync the entire file (pi does this itself during migrations). Used when cascade-reparenting children on delete.

ToolCall field normalization

Pi stores toolCall blocks as {type:"toolCall", id, name, arguments} but ToolCallContent uses {toolCallId, toolName, input}. normalizeToolCalls() in lib/normalize.ts handles this — called in both session-reader.ts (file load) and ChatWindow.handleAgentEvent() (streaming).

New session tool preset

Tool names are passed at session creation (POST /api/agent/new → toolNames[]). For existing sessions, the active preset is inferred on mount via get_tools → getPresetFromTools(). When tools are fully disabled (toolNames = []), rpc-manager.ts passes an empty tool allow-list and forces agent.state.systemPrompt = "" after startup/reload/resource discovery.

The last preset explicitly selected by the user is stored in browser localStorage and initializes fresh-session composers only. Existing sessions never trust that preference; they use their live get_tools state or pi's default when no wrapper exists.

Model defaults for new sessions

GET /api/models returns defaultModel read from ~/.pi/agent/settings.json. ChatWindow pre-selects this on mount for new sessions. Explicit browser model/thinking selections are applied atomically during AgentSession construction, then lib/startup-preferences.ts persists their effective values without replaying set_model/set_thinking_level; implicit enabledModels fallbacks and thinking pins are not persisted.

enabledModels scoping

The enabledModels setting uses pi's --models syntax: minimatch globs against provider/modelId or a bare modelId, fuzzy matching for non-glob patterns, and an optional :thinkingLevel suffix. Never compare those patterns as literal strings — lib/model-scope.ts delegates to the SDK's resolveModelScopeWithDiagnostics() so pi-web and the TUI agree on the visible model list, and falls back to all available models when patterns resolve to nothing. startRpcSession() resolves that scope before creating an AgentSession and passes the selected initial model, thinking pin, and SDK-native scopedModels atomically; GET /api/models reuses the helper only for selector data, thinkingLevelPins, and modelScopeWarnings display.

SSE reconnect on page refresh mid-stream

On ChatWindow mount, GET /api/agent/[id] is called. If state.isStreaming === true, SSE is reconnected automatically. thinkingLevel and isCompacting are also synced from this response.

Compaction SSE events

Newer pi emits compaction_start / compaction_end; older versions emitted auto_compaction_start / auto_compaction_end. handleAgentEvent accepts both sets to keep isCompacting in sync. Manual compact is a blocking POST — the button stays disabled until the response returns.

Running state polling + reconciliation

  • The sidebar polls /api/agent/running every 2.5 seconds while the tab is visible and pauses polling in background tabs. The session-list response remains the initial fallback.
  • useAgentSession treats per-session SSE as primary for chat events and opens it before each prompt. prompt_done completes the current UI stage and notification immediately, but the idle SSE stays open for a 30-second grace window and is reused by the next prompt. agent_start cancels that close timer; agent_settled finishes extension-injected runs that have no wrapper-level prompt_done and starts a fresh grace window. Do not close on the first agent_end: retries, compaction, and extension-queued messages can continue the same logical prompt.
  • While a run is active, useAgentSession periodically calls GET /api/agent/[id] and also reconciles on visibilitychange/online. This fixes missed terminal events from background tabs or half-open connections.
  • Prompt runs use a monotonic run id; late SSE or slow reconciliation responses from an old run must be ignored so they cannot resurrect stale streaming bubbles.

Worktrees and project grouping

  • lib/worktree.ts resolves linked worktree top-levels back to the main repo projectRoot; listAllSessions() attaches that to each SessionInfo so all worktrees for one repo are grouped together in the sidebar.
  • Worktree operations are served by /api/worktrees and guarded by the same allowed-root rules as /api/files.
  • New worktrees are created under <repoRoot>-worktrees/<sanitized-branch>. Existing branches are reused; otherwise git worktree add -b creates the branch.
  • Removing a dirty worktree returns 409 with { dirty: true } so the UI can ask before retrying with force.
  • Sessions whose cwd points at a removed worktree are inferred back into the main project instead of becoming a phantom project row.
  • git prints POSIX-style absolute paths even on Windows, so every path read out of git goes through toNativePath() (lib/paths.ts) before it is compared or returned. Compare paths with samePath(), never === — raw equality made isTopLevel permanently false on Windows and hid the worktree switcher entirely. Branch names are not paths and must keep their forward slashes. Browser code cannot apply Node path rules, so /api/worktrees resolves currentWorktreePath server-side; the sidebar must use that identity for highlighting and removal fallback.

File access allow-list

  • /api/files is intentionally not a general filesystem browser. Allowed roots come from session cwds, their resolved project roots, ~/pi-cwd-*, and roots explicitly added with allowFileRoot().
  • /api/cwd/validate, /api/default-cwd, and /api/worktrees call allowFileRoot() when they make a new location browsable.
  • Allowed roots are stored slash-normalized, but that is a Set-key convention, not a correctness requirement: isPathWithinRoots() (lib/path-security.ts, the single implementation behind isFilePathAllowed()) re-resolves and case-folds both sides, so either path form authorizes correctly. Keep that one implementation — it is the security boundary.

Plugins and skills

  • /api/plugins uses pi's SettingsManager + DefaultPackageManager for global/project package install, remove, update, enable, and disable. Disabling writes empty extensions/skills/prompts/themes arrays for that package entry.
  • /api/skills uses DefaultResourceLoader so settings paths, package skills, and project .agents/skills are listed the same way the runtime sees them.
  • Skill toggling edits only the disable-model-invocation frontmatter key on the target SKILL.md; keep that surgical so user formatting survives.
  • /api/skills/install shells through npx skills add ... --agent pi; project installs run with the selected cwd.

Auth and model config

  • ModelsConfig combines models from ~/.pi/agent/models.json with provider auth status from pi's AuthStorage/ModelRegistry.
  • Provider listing is capability-driven, never id-driven: lib/provider-listing.ts decides membership from auth.apiKey.login / auth.oauth plus the stored credential type, so dual-auth providers (anthropic and github-copilot today — which providers declare both changes between SDK releases, so never assume it from an id) appear exactly once and never fall through both lists (#309). lib/provider-listing-runtime.ts adapts ModelRuntime to those pure helpers.
  • auth.json holds one credential per provider and ModelRuntime.logout() deletes whichever it is. The delete routes therefore use removeStoredCredentialIfType() to compare and delete under the same file lock used by pi's auth storage. ModelsConfig also refreshes both provider lists after any auth change — refreshing one leaves a dual-auth provider rendered twice.
  • OAuth/device-code/manual-code flows are streamed by GET /api/auth/login/[provider]; manual code responses POST back with a short-lived token stored in globalThis.__piLoginCallbacks.
  • API-key routes store and remove keys through AuthStorage. Status endpoints must never return the raw key.
  • The model test route is app/api/models-config/test/route.ts; app/api/models/test/ is not a real route.

Completion sound

  • hooks/useAudio.ts stores the toggle in localStorage as pi-sound-enabled and reuses one AudioContext.
  • Browser autoplay policy means sound must be unlocked from a user gesture; ChatInput calls the unlock hook from interactive controls, and ChatWindow plays the tone from onAgentEnd.

Exported session HTML

  • /api/sessions/[id]/export delegates to pi's export helper, then patches recursive tree helpers in the generated HTML to iterative versions so very deep linear sessions do not overflow the browser call stack.

Pi Session File Format

Location: ~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl

{"type":"session","version":3,"id":"<uuid>","timestamp":"...","cwd":"/path","parentSession":"/abs/path/to/parent.jsonl"}
{"type":"model_change","id":"<8hex>","parentId":null,"provider":"zenmux","modelId":"claude-sonnet-4-6","timestamp":"..."}
{"type":"message","id":"<8hex>","parentId":"<8hex>","message":{"role":"user","content":"..."}}
{"type":"message","id":"<8hex>","parentId":"<8hex>","message":{"role":"assistant","content":[...],...}}
{"type":"message","id":"<8hex>","parentId":"<8hex>","message":{"role":"toolResult","toolCallId":"...","content":[...]}}
{"type":"compaction","id":"<8hex>","parentId":"<8hex>","summary":"...","firstKeptEntryId":"<8hex>","tokensBefore":N}
{"type":"session_info","id":"...","parentId":"...","name":"user-defined name"}

entryIds[] in SessionContext is a parallel array to messages[] — maps each displayed message back to its .jsonl entry id, used for fork and navigate_tree calls.

CSS Variables (app/globals.css)

--bg --bg-panel --bg-hover --bg-selected --border
--text --text-muted --text-dim
--accent --user-bg --tool-bg
--font-mono