Federico Jaramillo Martinez
bd4a891b95
Startup progress could still be shown on the wrong session's row. Routing by known session id first closed the case where the browser knew the other session, but left open the case where it does not -- which the browser is designed to produce. While a create is pending for a workspace, applyCreatedSession deliberately withholds a session.created event for that workspace and stashes it, to avoid a duplicate row. So during exactly the window this feature exists for, a session created by an agent's spawn or by another tab is intentionally absent from the session list. Its startup events carried an unrecognised id and a matching cwd, and were routed onto the user's pending create row, showing a phase and a label belonging to another session. Workspace path was never evidence of identity; it was the only key both sides happened to share. Give them a real one. The browser already invents a temporary row id for a pending create, so it now sends that id with the create request as an opaque startupToken; the daemon carries it through construction, echoes it on the startup events it publishes for that construction, and the browser matches it exactly. The token is a throwaway label the daemon never interprets. It never becomes the session id: activity.sessionId still carries Pi's SessionManager id, which remains how an open of an already-known session is routed. With exact identity available, the guessing is deleted rather than gated. startupProgressPendingStart goes entirely, and with it the selected-machine comparison, the cwd filter, and the single-match ambiguity rule: a second concurrent create carries a different token, and a foreign workspace or non-selected machine carries no token this browser is waiting on, so those cases stop existing rather than needing detection. One Map lookup replaces a filtered scan. cwd comes off the event, since it existed only as the routing key and nothing else read it. No compatibility path is needed. session.startup is unreleased -- checked against the published tarball, not only git tags -- so no deployed daemon emits these events and no deployed browser parses them. An older daemon ignores the extra request field; a newer daemon talking to an older browser degrades to the pre-existing generic wording, as does any unmatched token. One silent behaviour change to state plainly: startupProgress guarded on `sessionId === "" || cwd === ""`. Removing cwd from the event removes the meaningful half of that guard, and that half had no test. The session-id half is kept, which is the half that actually protects honest reporting. The replaced ambiguity test is rewritten rather than dropped, so the same three scenarios still pin the user-visible guarantee -- no match means the generic wording stays -- now including the reproduced foreign-session case, which fails against the previous code. Session creation ordering, semantics, and queueing are unchanged; the token is a passthrough label read only to build an event.
PI WEB
PI WEB is a web UI for Pi Coding Agent that keeps agent sessions running in real workspaces on your machine or server.
Run agents where your code, tools, credentials, and build caches live. Supervise them from any browser.
Website and docs: https://pi-web.dev/
Why PI WEB?
Agentic development works better when the work environment is persistent.
PI WEB lets you:
- keep Pi Coding Agent sessions alive after browser disconnects;
- run agents inside real repositories and git worktrees;
- supervise multiple sessions in parallel;
- switch between laptop, phone, tablet, and desktop;
- use a server, workstation, or remote dev box as your agent runtime;
- manage projects, workspaces, files, terminals, sessions, and remote machines from one web UI.
Your browser is the control surface. The work stays where it can keep running.
Quick start
Requirements:
- Node.js 22.19.0 or newer
- npm
- Pi Coding Agent
>=0.82.1 <0.83, configured for your user - git and the development tools your agents need
Install and start PI WEB as per-user services:
npm install -g @jmfederico/pi-web --allow-scripts=node-pty
pi-web install
pi-web doctor
On npm 12, the scoped flag lets node-pty prepare its required native module without enabling install scripts for other dependencies.
Then open:
http://127.0.0.1:8504
Useful commands:
pi-web status
pi-web logs
pi-web restart
pi-web doctor
pi-web version
pi-web uninstall
For more install options, including one-line install, Pi package install, WSL/manual usage, and remote access, see the installation guide.
Core model
PI WEB organizes work like this:
Machine a local or remote PI WEB runtime endpoint
Project a folder on that machine
Workspace a git worktree, or the project folder for non-git projects
Session a Pi Coding Agent chat running inside a workspace
A typical flow:
- Add a project.
- Choose a workspace or git worktree.
- Start a session.
- Let the agent work.
- Come back later from any browser.
Remote-first development
PI WEB is designed for remote AI-driven development.
Instead of tying agent work to your laptop session, run PI WEB on a machine that stays available: a server, desktop, cloud VM, home lab machine, or remote dev box.
Use a private network, SSH tunnel, trusted reverse proxy, or federated PI WEB machine setup when accessing it remotely.
Read more: Remote-first development
Machines and fleets
PI WEB can register other PI WEB runtimes as remote machines. One browser-facing PI WEB instance can proxy projects, files, git state, sessions, terminals, activity, Pi package management, and selected-machine settings from trusted remote machines.
When a remote machine is selected, Settings tabs label their target. Pi packages, PI WEB plugin enablement, session daemon toggles, external file access, and upload defaults target the selected machine. Gateway/server settings such as host, port, allowed hosts, registered machines/tokens, and keyboard shortcuts stay local to the gateway/browser.
Read more: Fleet and machines guide
PI WEB plugins
PI WEB supports trusted browser-side plugins that can add actions, workspace panels, and workspace metadata. Use Settings → PI WEB plugins to enable or disable them on the selected machine.
Pi packages are a separate Pi package-manager concept. A Pi package may include a PI WEB browser plugin, but installing a package and enabling its browser plugin are different operations.
Read more: PI WEB plugin guide and API
Configuration
Global config lives at:
$PI_WEB_CONFIG
~/.config/pi-web/config.json
Project-local PI WEB config lives at:
<project>/.pi-web/config.json
Common configuration includes host/port, path access, uploads, PI WEB plugin enablement, shortcuts, and session daemon options. In Settings, machine-affecting config targets the selected machine; gateway host/port/allowed-hosts, remote machine registration, tokens, and keyboard shortcuts stay local.
Read more: Configuration reference
Development
Clone the repository and run:
npm install
npm run dev
Open the Vite URL, usually:
http://localhost:8505
For the split development setup:
npm run dev:sessiond
npm run dev:web
npm run dev:client
Validate changes with:
npm run verify
Security model
PI WEB assumes trusted users, trusted repositories, and trusted server paths.
It is not a sandbox, permission system, or multi-tenant platform. Do not expose it directly to the public internet without a trusted network, firewall, VPN, SSH tunnel, or authenticated reverse proxy.
Documentation
License
MIT © 2026 Federico Jaramillo Martinez. See LICENSE.