pi-web README

The project's README from github.com/agegr/pi-web. As one markdown file: README.md.

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.

Pi Web displaying a pi session with structured Markdown, tool calls, and project navigation

Features

Quick Start

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

To update, stop the running process with Ctrl+C and run the same install command again. To uninstall, run npm uninstall -g @agegr/pi-web.

Configuration

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.

Option or environment variable Purpose Default
--help, -h Print startup options and exit —
--port <port>, -p <port>, or PORT Server port 30141
--hostname <host>, -H <host>, or PI_WEB_HOSTNAME Bind hostname 127.0.0.1
--no-open or PI_WEB_NO_OPEN=1 Do not open a browser automatically Browser opens
PI_WEB_SKIP_VERSION_CHECK=1 Disable Pi Web update checks Unset
PI_WEB_ALLOWED_HOSTS Additional exact proxy or custom hostnames, comma-separated Unset
PI_WEB_PASSWORD Enable browser password login; API clients may use Basic Auth with username pi Authentication disabled
PI_WEB_IDLE_TIMEOUT_MS Session idle timeout in milliseconds, up to 2147483647; 0 disables idle shutdown; invalid or out-of-range values use the default 600000 (10 min)

For example:

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

Remote Access

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.

HTTP Proxy

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

Notes

Downstream Session Context Menu

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 preserves the browser's native context menu. This hook is browser-side and independent of Pi agent extensions.

Extension Session Liveness

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.

Development

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.

Contributor guides: Internationalization and Release process.

Repository Layout

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

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

License

MIT

pi-web (agegr/pi-web)

Searching Database…

7.4K ·GitHub
Pi-web
Что это такое?Локальный браузерный интерфейс для агента pi: можно просматривать и продолжать диалоги, запускать ходы агента, настраивать модели и просматривать файлы проекта — используются те же данные, что и в pi CLI.
Это десктопное приложение или работает в моём браузере?Оно запускается как небольшой локальный веб-сервер командой pi-web, а пользуетесь вы им через браузер. Интерфейс использует те же файлы настроек и сессий pi, поэтому CLI и этот UI всегда синхронизированы.
Как его запустить?Установите глобально через npm install -g @agegr/pi-web и запустите pi-web — сервер поднимется на порту 30141 и сам откроет браузер. Чтобы обновить, просто повторите ту же команду установки.
Нужно ли что-то заранее установить, чтобы всё работало?Нужен Node.js 22.19.0 или новее. Если провайдер модели ещё не настроен, вы сможете войти в аккаунт или добавить API-ключ в панели Models внутри Pi Web.
Можно ли открыть его с другого компьютера, или он строго локальный?По умолчанию он слушает только 127.0.0.1. Удалённый доступ возможен, но вход по паролю не шифрует трафик, поэтому в README советуют использовать HTTPS через обратный прокси или VPN и ни в коем случае не открывать его по обычному HTTP.
Где хранятся мои сессии и файлы проектов?Всё остаётся на вашем компьютере: данные pi читаются из ~/.pi/agent, а в браузере файлов видны только те рабочие каталоги, которые вы выбрали в Pi Web, — это не обзор всей файловой системы.
Что я могу делать с прошлыми диалогами?В рабочей области сессий можно просматривать, продолжать, переименовывать, экспортировать и удалять диалоги, сгруппированные по проектам; там же видно состояние запусков, использование контекста, стоимость и детали компакции. Ветвление доступно двумя способами: начать независимую сессию с более раннего сообщения или создать ветку внутри сессии через Edit from here.
А мои Git worktree он поддерживает?Да — переключаться между чекаутами можно прямо из боковой панели, при этом сессии одного репозитория остаются сгруппированными вместе, а диффы Git по файлам проекта можно просматривать.
Какие типы файлов он умеет показывать?Исходный код, Markdown, изображения, аудио, PDF и DOCX — с автоматическим обновлением. Файлы проекта также можно просматривать и загружать прямо из интерфейса.
На каких языках доступен интерфейс?Английском, китайском упрощённом и китайском традиционном. При первом запуске берётся язык вашего браузера, а переключатель находится в верхней панели.
What are similar projects?wicked-studio, control-center, multi-agent-discuss, wechat-miniapp-radar, codeburn, Resume-Matcher, html-anything, neko-master
Which topics is it in?i18n, nextjs, git, dashboard, coding-agent, web-app, react, npm, chinese, ai-agents, llm, nodejs
Creator
agegr
Size
9 MB
Stars
7.4K
Updated
CommitOct 15Releasev0.12.2Oct 15
Age
6mo
Commits · 90 Days