agegr/pi-web

中文文档 | 日本語 | Русский

Local browser UI for the pi coding agent. Pi Web uses the same local configuration and session files as pi, so you can browse and resume conversations, run agent turns, configure models and resources, and inspect project files from a browser.

Try the interactive demo → The real Pi Web UI runs entirely in your browser, with sample sessions, files and models. There is nothing to install; replies are pre-written and no model is called.

• Session workspace: browse, resume, rename, export, and delete conversations grouped by project, with running state, context usage, cost, and compaction details.
• Two ways to branch: New session creates an independent session file from an earlier message; Edit from here creates a branch inside the current session.
• Project file tools: browse and upload files, inspect Git diffs, and preview source, Markdown, images, audio, PDFs, and DOCX files with automatic refresh.
• Git worktrees: switch checkouts from the sidebar while keeping sessions from the same repository grouped together.
• Web-based configuration: manage provider login and API keys, models, model tests, plugin packages, and skills without leaving Pi Web.
• English, Simplified Chinese, and Traditional Chinese UI: Pi Web follows the browser language initially and provides a language switcher in the top bar.

Pi Web requires Node.js 22.19.0 or newer. Check your version with node --version, then run:

npx @agegr/pi-web@latest

The CLI opens a browser after the server is ready. If it does not, open http://127.0.0.1:30141. Pi Web listens only on 127.0.0.1 by default.

If no model provider is configured yet, open the Models panel to sign in or add an API key.

To install the pi-web command globally:

npm install -g @agegr/pi-web@latest
pi-web

Commands:

pi-web version          # print the installed version
pi-web status           # list running servers
pi-web stop [--port N]  # stop a running server
pi-web open [--port N]  # open a running server in the browser
pi-web update [--check] # update a global npm install

To update, run pi-web stop, then pi-web update (or run the same install command again). To uninstall, run npm uninstall -g @agegr/pi-web.

For port and hostname, command-line options override the corresponding environment variables. Either --no-open or PI_WEB_NO_OPEN=1 disables automatic browser opening. Run pi-web --help (or -h) to print startup options and exit without starting the server. Unknown options exit with an error.

Set PI_WEB_APP_NAME before starting the server (for example, PI_WEB_APP_NAME='Work Pi' pi-web). After changing it, restart the server to serve the new manifest; no rebuild is required. Updates to the name of an already installed PWA are managed by the browser and are not guaranteed to appear immediately. This does not change the page title or icons.

For example:

pi-web --help
pi-web -p 8080 -H 0.0.0.0 --no-open

Binding to a non-loopback address exposes an agent that can execute high-privilege actions. On a trusted LAN, require a long random password:

PI_WEB_PASSWORD='a-long-random-password' pi-web --hostname 0.0.0.0

Password authentication does not encrypt the connection. Do not expose Pi Web over plain HTTP to the internet; use HTTPS through a trusted reverse proxy or a trusted VPN. If a reverse proxy sends an external hostname, add that exact name to PI_WEB_ALLOWED_HOSTS. This allow-list does not change the address Pi Web binds to.

Server-side model and API requests honor the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables.

On macOS or Linux:

HTTP_PROXY=http://127.0.0.1:7890 \
HTTPS_PROXY=http://127.0.0.1:7890 \
NO_PROXY=localhost,127.0.0.1 \
npx @agegr/pi-web@latest

On Windows PowerShell:

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:NO_PROXY = "localhost,127.0.0.1"
npx @agegr/pi-web@latest

• Agent data: Pi Web reads pi data from ~/.pi/agent by default, including session files under sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl. Set PI_CODING_AGENT_DIR to use another pi agent directory.
• Filesystem access: Pi Web must be able to read the agent data directory and the working directories recorded by its sessions. Run Pi Web in the same filesystem environment as pi when sharing existing sessions.
• Shared configuration: the Models panel uses pi's model, settings, and credential storage, so changes are visible to both interfaces.
• File access boundary: the file browser is limited to working directories selected in Pi Web and project or session roots it already knows about; it is not a general filesystem browser.
• Git worktrees: see Worktrees in Pi Web for switcher visibility, worktree creation, and removal behavior.

Electron wrappers and other downstream integrations can provide a session-row context menu without patching SessionSidebar. Listen for the cancelable pi-web:session-row-contextmenu browser event and call preventDefault() synchronously when the integration will handle it:

window.addEventListener("pi-web:session-row-contextmenu", (event) => {
  event.preventDefault();
  const { id, path, cwd, name, clientX, clientY, refresh } = event.detail;

  void openSessionMenu({ id, path, cwd, name, clientX, clientY }).then((changed) => {
    if (changed) refresh();
  });
});

The detail object contains id, path, cwd, optional name, pointer coordinates, and a refresh() callback for actions that change the session list. If no listener cancels the extension event, Pi Web opens its built-in session menu (pin, rename, fork, mark read or unread, archive, open in new tab, delete) at the pointer instead of the browser's native context menu. The row's ⋯ button always opens the built-in menu and does not dispatch the event. Sessions not yet saved to disk get no built-in menu, so the native one still appears for them. This hook is browser-side and independent of Pi agent extensions.

Server-side Pi extensions with detached work can prevent automatic idle session eviction through the versioned global registry:

const liveness = globalThis[Symbol.for("@agegr/pi-web/session-liveness/v1")];
const release = liveness?.version === 1
  ? liveness.register({
      name: "my-extension",
      sessionId,
      sessionFile: sessionFile || undefined,
      isActive: () => detachedJobs.size > 0,
    })
  : () => {};

Register once per active extension session and call the returned idempotent release function on session shutdown, replacement, or reload. isActive must be synchronous, cheap, and scoped to the supplied exact session id or file. Provider errors fail safe by preserving that session. This lease only affects automatic idle eviction; explicit shutdown and Stop fallback cleanup still take precedence.

npm install
npm run dev

The development server runs at http://127.0.0.1:30141. Run the common checks with:

npm test
node_modules/.bin/tsc --noEmit
npm run lint

Do not run next build or npm run build during normal development. It writes to .next/ and can interfere with the development server; leave builds for release work.

Before starting on a feature, read Contributing for what is in scope and the pull request checklist.

Contributor guides: Internationalization and Release process.

app/             Next.js UI and API routes
components/      React UI components
hooks/           Client state and interaction hooks
lib/             Session, agent, model, file, Git, and security logic
public/          Static assets and PWA files
bin/             npm CLI entrypoint and launch option parsing
docs/            Focused user and contributor guides
demo/            Static browser demo published to GitHub Pages (see demo/README.md)

See AGENTS.md for the architecture notes and detailed file map.

MIT