PROJECT TOPICS
INSTALL REFERENCE
dsh plugin --profile web add github:xing-shuyin/pi-web-ui
该命令指向仓库当前默认分支；尚无绑定当前 commit 的完整验证结果。
PROJECT README
English | 简体中文
Just open your browser — get all your work done.
Chat, code, review, manage files, use the terminal — all in one browser tab. No IDE, no terminal app, no context-switching.
A browser cockpit for AI coding agents (pi / DSH) built around one idea: you only need a browser to get everything done. The agent runs server-side and streams events to the browser over WebSocket: thinking blocks, tool calls, file trees, a built-in terminal, model management, theme switching, and a full settings panel — tuned for daily development.
Requirements — Node.js ≥ 22.19 and a configured pi install.
Building with DSH?
dsh-ui-tools is the author's companion project for building and extending UI tools in the DSH ecosystem.
QQ群 1126050727
| 💬 Chat that works like you do | 🖼️ Files & images | 🧩 Extensible by design | 🔒 Private by default |
|---|---|---|---|
| Streaming replies, steer & follow-up queueing, slash commands, multiple conversations per project, edit-&-re-ask. | Attach files, paste images, ask about pictures (vision bridge), preview anything with GBK fallback. | Drop-in UI plugins (extra top-bar tabs + agent tools) and standalone themes — no rebuild, no restart. | Loopback-only, credential-safe: provider keys & headers never reach the browser. |
/ opens a command picker (built-in / extension / template / skill); built-ins include /new /model /compact /cwd /thinking /resume, plus /help (command list) and /copy (copy last reply). /new takes an optional first prompt (/new fix the failing test) and sends it as the new chat's first message.0 = fail immediately); when retries run out the failed turn is marked red with a one-click Retry button.HH:MM timestamp, and every text block has a copy button. Attachments render as their own collapsible card with a mode chip (lines / ref / bridged / inline n lines), a copy button and a vision-bridge “transcribed” note; a skill invocation becomes a skill card with the full SKILL.md, next to the arguments you typed.📁 <path> to open the folder picker: type a path (Tab completes), ↑ goes up one level, 💻 jumps to the computer root so you can change drives, click a folder to enter it and hit Select — or Select this folder to take the folder you are browsing. ＋ New folder creates a directory on the spot; Esc or a click outside closes it./cwd <path> from the input box (/cwd alone reports the current directory).--cwd <dir> / PI_WEB_CWD.<agentDir>/sessions/--<cwd>--/, i.e. the same transcripts the pi CLI/TUI writes, so the browser and a terminal pi session share one list per project. Rename (✎ — the same session_info entry pi's /name writes) and two-step delete.subagent_spawn, with optional model override or a template's model); collect results without polling via subagent_wait_all (blocks until every subagent finishes, then summarizes results/errors). Manage them like a chat right in the left panel: view live output, inject follow-ups (steer), abort, dismiss — failed runs surface a red dot in the running list and an error notice in the main chat. In-memory sessions — they never touch the history / resume list, and can be nested.subagent_templates tool and subagent_spawn(template="…"), or spawns without one (default = follow the main conversation's current model and thinking level, or the global default subagent model set in the same panel). A template that sets them pins that exact combination (unsupported thinking levels are clamped by the SDK to the nearest one the model supports). Disabled templates stay in the panel for re-enabling but become invisible to the AI tools (can't be listed or picked). Templates are shared globally across browser clients (<dataDir>/subagent-templates.json). Six built-in templates (review / implement / research / scout / audit / delegate, adapted from the pi-subagents community projects) seed the list on first run — marked 「Built-in」, editable and deletable like any other.inline (≤12 KB), reference (path only), lines (selected ranges) — over-limit ones degrade automatically.lines), GBK fallback decoding, binary hex view, media preview over HTTP with Range support, and a download button.fs.watch) and re-lists on change; oversized directories show a truncation warning./ on POSIX), the breadcrumb jumps straight to any level, .. goes up, and a listing that vanished or lost its permissions degrades into an empty list plus a warning instead of an error page.node_modules, .git, dist, .venv, …) and caps at 500 entries, Windows hides only dependency/VCS/data directories and caps at 2000, and both say when they truncated.lines), zoom 50–200 %, a word-wrap toggle and fullscreen.cmd. Up to 16 live terminals (agent-opened ones don't count), each keeping its own 8000-line scrollback while you switch tabs; tabs can be renamed inline, closed (which really kills the process) and show their exit code in the scrollback..pi/commands.json list (name + command + cwd, ${pwd} expands to the workspace): click a row to run it (a same-titled tab is reused and restarted, VS Code task style), add/edit/delete entries, and reload the file from disk.bash tool then runs inside a visible persistent terminal instead of a hidden process, so shell state (cd, venv, ssh) survives between calls; a silence threshold (default 15 s, 0 = wait forever) moves a quiet command to the background, and head/tail trim what the model has to read.git add -A && git commit), a branch picker that groups local and remote-tracking refs (picking a remote one creates a local branch tracking it), and detached-HEAD / ↑ahead ↓behind badges. The “Commit tree” tab loads git log --graph with per-commit diffs. Writes (commit / branch switch / push / pull) run in the visible terminal and the view follows them there; the panel refreshes itself when the repository's real git dir changes (worktrees included) and via a 30 s fallback poll, so commits made outside the browser show up by themselves.:root palette overrides on top of the single layout stylesheet (default dark + bundled light/dark palettes). See Themes for how to add your own or contribute one.models.json in the UI and set per-provider API keys (keys/headers never leave the server).<agentDir>/provider-keys.json): add a second key without losing the first, activate another by name, remove one (dropping the active key promotes the next). The picker lists each key separately, so picking a model under a key switches to it — and only nicknames reach the browser.baseUrl, key, optional auth header) with per-model metadata (context window, max output, text/text-image, reasoning); Fetch models probes /models server-side (so a LAN/loopback endpoint works despite CORS) and merges what it advertises, and an existing provider can be re-probed in place. Hand-edited models.json is picked up with Reload models.json (comments allowed, like the SDK).{{token}} compose template over 11 sources (soul / tools / guidelines / pi docs / append / persona / terminal / markers / context / skills / cwd) with click-to-append token chips, per-source overrides (an auto badge, “seed from default”, per-source reset; environment-derived sources stay read-only), and two viewers showing the prompt actually in effect and the tool schema actually sent to the model.SKILL.md into the prompt instead of its catalog line (8 KB per file, 32 KB total).npm:-installed ones (runs pi remove npm:<pkg> in a reusable terminal tab).subagent_* tools (default on), edit_soft (default off), delegate_task, ask_user_question and todo_list (default on). Toggling is live (no reload) and the tools stay registered so they can come back; bash and the SDK's own edit/read are deliberately outside the catalog and cannot be disabled.[[todo:new:<subject>]] / [[todo:set:<id>,in_progress]] / [[todo:remove:<id>]] / [[todo:dep:<id>,blocks=<id>]] for the task list, [[notify:<level>:<message>]] for a non-interruptive notice, and [[conv:rename:<title>]] to retitle the chat. Markers are applied as soon as a reply bubble is final, a bad marker comes back as a browser notice, and the task list also renders as a live widget under the file tree (N/M done with ✓ / ◐ / ○) that follows the active conversation and survives a reload — it is stored in that conversation's own session branch. Settings → Tools has a master switch plus one switch per marker (these are global, shared by all browsers).edit_soft — a looser edit (default off) for when indentation or whitespace makes the built-in tool fail: exact substring first, then trimmed line-core matching, newText written verbatim with the file's line endings/BOM preserved, and a diff + unified patch in the result. It also tolerates sloppy input (a JSON string, a bare object, legacy top-level oldText/newText).delegate_task — hands a specialist template a six-section brief (TASK / EXPECTED OUTCOME / REQUIRED TOOLS / MUST DO / MUST NOT DO / CONTEXT) validated on the server: a missing template, a task under 20 characters or any empty section is rejected, and the error tells the model which templates it may use. Cards render the brief as labelled sections, and a finished delegation gets a button that jumps to the subagent's conversation.ask_user_question — the pi engine has no questionnaire tool, so pi-web-ui adds one: the model asks structured questions (single/multi-select with rich option previews, plus free text) which open as a dialog; answers go back as the tool result, cancelling returns a tool error, waiting for you is exempt from the tool watchdog, and an unanswered questionnaire survives a page refresh or reconnect.<dataDir>/mcp.json ({"servers":{"github":{"command":"node","args":["mcp.js"],"cwd":"/x"}}}) and every tool a stdio MCP server advertises becomes an ordinary agent tool, executed server-side; one server failing to start only logs a line and leaves the others working. The file is hot-reloaded: saving it applies within a second or two, no restart needed — and only the servers whose spec actually changed are restarted (a malformed file is reported and the running servers are kept).setWidget renders live panels under the file tree (click a title to open it centred), setStatus puts text in the status bar, notify raises a toast, and select / confirm / input open an inline request panel above the composer with Markdown-rendered options (Esc cancels). ANSI colour codes in widget text are stripped, so extension footers don't arrive as escape-sequence noise./commands (badge “plugin”, executed server-side without spending tokens), register background tasks with their own stop button, declare a settings form, subscribe to run/tool/conversation events, and reach the host from their client bundle via window.__piWebUiHost. See Plugins../-relative so sub-path deployments work) means “Install app” in Chrome/Edge or “Add to home screen” on mobile gives you its own window and icon./ws, /api, /themes or /plugins; a new worker takes over already-open pages immediately.<dataDir>/locales/, so you can also drop a valid pack file there by hand for a fully offline install.PI_WEB_LOCALE), then English; once you pick one it sticks.subagent_list.git diff HEAD; on fail the feedback is injected as steer until it passes (or the round cap is hit).PI_WEB_ENGINE=pi|dsh (default pi). The pi engine runs the agent in-process via the pi SDK; the DSH engine runs the official @deepseek-ai/dsh (DeepSeek Harness) runtime as a subprocess. /api/health reports engine; the footer shows a DSH badge.ask_user_question.deepseek-v4-flash-vision-exp); text-only models get a text-transcription bridge instead.ask_user_question surfaces as a browser dialog (single/multi-select + free text) with queueing and a countdown.mcp.json) are bridged into the DSH runtime, so the DSH model can call them (executed server-side)..yml Cordis patches into <dataDir>/dsh-patches/ to extend the runtime and reload from Settings; the Settings → Plugins page lists them with size/mtime and the resolved path, and a broken file is skipped with its error on the runtime's stderr.How DSH differs from the pi engine (worth knowing before you switch):
high — asking for another level answers “DeepSeek V4 only supports high thinking”.<dataDir>/dsh-sessions/ (separate from the pi engine's transcripts) and are swept after PI_WEB_DSH_SESSION_RETENTION_DAYS (90); open conversations are capped at 8 per project; a crashed runtime is restarted with 1 s/3 s/9 s back-off, at most twice per 60 s, then it stops and points you at the API key and the DSH dependencies.workspace-write sandbox with approvals off — your Stop button is the control. Questionnaires are a one-question-at-a-time wizard with option previews and a countdown./compact, /reload, extension hot-reload, subagent templates, custom providers / multiple keys, provider model probing, installing the pi CLI, the vision bridge and the per-tool switches.explorer rather than to the server, so a browser you opened yourself isn't reported as “started by the agent”.PI_WEB_TOOL_TIMEOUT_MS; questionnaires are exempt).PI_WEB_STALL_NOTIFY_MS, 0 = off) you get a warning naming the conversation, without aborting it.PI_WEB_HOST=0.0.0.0 for LAN / containers.PI_WEB_TOKEN accepts any of Authorization: Bearer …, X-PI-Token: …, ?token=… or the pi_web_token cookie. A ?token= link logs you in once, strips the token from the address bar and stores the cookie; every authorised request refreshes it and a stale cookie is expired on the 401 response, so after changing the password one correct ?token= visit recovers permanently. /api/health stays open for probes.Origin: null (a file:// page) is rejected outright, and when a token is configured a bad credential is refused before the upgrade; PI_WEB_ALLOW_ORIGINS whitelist for reverse proxies.PI_WEB_ALLOW_HOSTS=host1,host2 adds a strict hostname allow-list on top of the always-on same-authority check.PI_WEB_TABS=chat,terminal,git exposes only those tabs: hidden tabs are also refused server-side (their messages answer with an explanation), and chat can never be switched off. PI_WEB_MANAGED=1 declares the instance as deployed from outside: the server refuses self-update, pi-CLI installs and marketplace installs with a reason, and the UI hides those entry points (the version chip becomes a plain label saying the deployment owns updates)... escapes (a path outside the workspace is only reachable through explicit absolute / machine browsing); inline /api/file streaming is limited to images, video and HTML, so a binary can never be smuggled through an <img> tag — anything else needs ?download=1 (attachment disposition). The HTML preview route is always served sandboxed.server status|quiesce|unquiesce) — refuses new prompts/forks/resumes (and, on the DSH engine, brand-new client connections) while in-flight runs finish.Authorization) are never sent to the browser, and provider API keys reach it only as nicknames.PI_WEB_UPLOAD_RETENTION_DAYS (14; 0 = never) are swept at startup and every 6 h; DSH sessions have their own 90-day sweep.Run key with a console-free launcher and a crash watchdog), and a desktop shortcut (server shortcut).server install --print prints the launchd plist / systemd unit / Windows launcher it would write and exits, so you can review it before installing.<agentDir>/npm/package.json; each row has its own Update, plus “Update all” and “Re-check all”, and the commands run in a visible terminal (pi update npm:<name> for pi extensions — the only command that updates the copy pi actually loads — and npm i -g <name>@latest for the rest). A “just published (<30 min)” warning tells you npm's cached metadata may be stale. On an instance owned by launchd/systemd/the Windows watchdog there is also a Restart service button; on a foreground instance there isn't, because nothing would bring it back.pi-web-ui plugins --check-updates compares each installed plugin's recorded commit with the remote HEAD and prints the exact update command; every install --force snapshots the outgoing version into <dataDir>/plugin-backups/ (newest 3 kept, and it auto-rolls back if the copy fails), so pi-web-ui plugins --rollback <id> can undo an upgrade./webui (from the bundled extensions/webui.ts): /webui starts a server on the first free port from 8787, and /webui --port 9000, --cwd <path>, --no-browser, status and stop manage it — one subprocess per pi session, killed when the session shuts down so no orphan servers linger.| Keys | What it does |
|---|---|
Enter |
Send. On touch-first devices Enter inserts a newline instead and Ctrl/Cmd+Enter sends (Windows touch laptops are treated as desktops). |
Shift+Enter |
Newline in the composer. |
↑ / ↓ |
Walk the global prompt history (persisted across conversations) when the caret is on the first/last visual line — auto-wrapped lines count, so ↑ inside a long one-paragraph draft moves the caret up a line instead of switching history; Esc returns to your draft. |
Ctrl/Cmd+K |
Global search over conversations, projects and workspace file names. |
Ctrl/Cmd+F |
Search inside the open conversation — Enter next hit, Shift+Enter previous, Esc closes. |
/ |
Open the slash-command picker (↑/↓ to move, Tab or Enter to complete, Esc to dismiss; typing a space closes it). |
Ctrl/Cmd+S |
Save while editing a file in the preview. |
Ctrl/Cmd+A |
Select all lines in the preview (when the caret isn't in a text field). |
Ctrl/Cmd+Enter |
Submit the edit-&-re-ask editor. |
Ctrl/Cmd+C / Ctrl/Cmd+V |
In the terminal: copy the current selection (no selection = ^C goes to the shell) / paste natively. |
Esc |
Close the preview, a dialog, the command picker, a questionnaire or an extension request panel — with unsaved preview edits it asks first. |
| Drag & drop | Dropping files anywhere in the window attaches them to the chat; over the file tree it uploads into the folder you dropped on; folders can't be dropped (expand and pick files). |
Chat with prompt templates
Run trajectory timeline (run-trace plugin)
Settings panel
Built-in terminal
Git source control panel
npm i -g pi-web-ui # global install (recommended)
npx pi-web-ui # or run without installing (latest, starts on :8787)
npm i -g . # or install the local checkoutnpm ≥ 12? npm 12+ blocks dependency install scripts by default (you'll see
npm warn install-scripts … blocked). node-pty is a native module, so allow its
script (the other two packages it lists are harmless no-ops — allowing them just
silences the warning):
npm i -g --allow-scripts=node-pty,@google/genai,protobufjs pi-web-ui@latestPrefer a window over a browser tab? Every release ships installers built from this repository by GitHub Actions:
⬇ Download the latest installers
— Windows (pi-web-ui-desktop Setup <version>.exe), macOS (.dmg) and Linux
(.AppImage).
The desktop shell reuses this very server: it spawns dist/server/index.js on a
random free loopback port and opens a window pointed at it (see
desktop/README.md). The web version is untouched — no
fight over port 8787, separate data directory, both can run side by side.
Nothing is code signed yet: on Windows SmartScreen shows an “unknown
publisher” prompt. macOS needs its own note: the bundle is only ad-hoc signed
(no Developer ID, no notarization) and the download carries a
com.apple.quarantine attribute, so Gatekeeper reports it as “damaged and
can't be opened” rather than “unidentified developer” — which means the usual
right-click → Open does not get you past it. Clear the attribute once
instead:
xattr -dr com.apple.quarantine /Applications/pi-web-ui-desktop.appThis affects both manual install paths — the .dmg you drag the app out of,
and the .zip you unpack yourself: the quarantine attribute is inherited by
the extracted .app either way. The in-app updater is unaffected, because it
runs the .zip through electron-updater, whose Squirrel helper clears the
attribute itself (clearQuarantineForDirectory:) — see the
code signing policy. Build it locally with
npm run desktop:dist.
pi-web-ui runs fine on Android via Termux, but node-pty
(the native dependency) needs a toolchain, and Android has a few quirks worth
knowing:
Install the build toolchain first — node-pty needs Python and a C
toolchain:
pkg install python clang make binutilsPoint the node-pty build at a dummy NDK path. On Android, gyp fails with
Undefined variable android_ndk_path unless the variable is defined:
GYP_DEFINES="android_ndk_path=' '" npm i -g --allow-scripts=node-pty,@google/genai,protobufjs pi-web-ui@latestIf pi-web-ui won't execute after install (the exec bit and/or shebang
can get mangled on Android): restore it:
chmod +x "$(command -v pi-web-ui)"
sed -i 's/\r$//' "$(command -v pi-web-ui)"Run it in the background with --no-browser (there is no desktop
browser to auto-open):
setsid nohup pi-web-ui --no-browser --cwd /path/to/workspace >~/pi-web.log 2>&1 &setsid detaches the server from the launching shell's process group, so
closing the Termux session doesn't take the server down — nohup alone is
not enough when the parent process group gets killed.
The [control] socket error: EACCES …/.pi-web/pi-web-ui.sock warning at startup
is harmless on Android: pi-web-ui server stop/restart won't work over the
control socket, but the web UI itself is unaffected.
Start (foreground)
pi-web-ui # foreground, http://localhost:8787Start flags & environment variables — every setting can be passed as a --flag on the command
line or set as an environment variable (flag wins). Pick whichever you prefer:
| Flag | Env var | Default | Purpose |
|---|---|---|---|
--port <n> |
PI_WEB_PORT |
8787 |
HTTP port |
--cwd <dir> |
PI_WEB_CWD |
current dir | workspace root (read/write/terminal) |
--data-dir <dir> |
PI_WEB_DATA_DIR |
~/.pi-web |
data dir (UI state, plugins, uploads, themes, locales) |
--engine <pi\|dsh> |
PI_WEB_ENGINE |
pi |
agent engine; --engine dsh = DeepSeek Harness |
--host <addr> |
PI_WEB_HOST |
127.0.0.1 |
listen address (0.0.0.0 for LAN/Docker) |
--agent-dir <dir> |
PI_CODING_AGENT_DIR |
~/.pi/agent |
pi config dir (auth.json, models.json, sessions, skills) |
--no-browser |
— | off | start without auto-opening the browser |
| env only | PI_WEB_TOKEN |
empty | optional shared auth token |
| env only | PI_WEB_DSH_* |
— | dsh runtime, patches & debug settings |
The two are equivalent — pick one:
pi-web-ui --engine dsh --port 9000 --cwd /path/to/project
PI_WEB_ENGINE=dsh PI_WEB_PORT=9000 PI_WEB_CWD=/path/to/project pi-web-uiFor the DSH engine also install the runtime (npm i -g @deepseek-ai/dsh@0.1.1-rc.2) and set a
DeepSeek API key (read from ~/.pi/agent/auth.json, set in the provider/API-key panel).
Stop
Ctrl+C in the terminal running it.pi-web-ui server stop. On Linux and Windows auto-start is kept (the next login/boot brings it back, until server uninstall); on macOS stop unloads the launchd agent, so it no longer starts at login — pi-web-ui server start brings it back.Update
npm i -g pi-web-ui@latest # upgrade to the latest published version
pi-web-ui server restart # restart the service to apply it (foreground: restart manually)Uninstall
npm uninstall -g pi-web-uiUninstalling does not delete your chats: the transcripts you see in the history panel live in <agentDir>/sessions/ (default ~/.pi/agent/sessions/, per project), and the rest of your state — UI settings, recent projects, plugins, uploads, themes, language packs — lives in <dataDir> (default ~/.pi-web/). Both survive uninstall, upgrade and reinstall; rerunning pi-web-ui server install afterward picks them up again (and if you plan to delete them, back up sessions/ and plugins/ first — an uninstall never touches either).
pi-web-ui server install --port 9000 --cwd /path/to/project # install + start
pi-web-ui server status # running? auto-start?
pi-web-ui server restart # restart (applies config/version changes)
pi-web-ui server stop # stop (auto-start stays)
pi-web-ui server start # start again
pi-web-ui server uninstall # remove the service entirely
pi-web-ui server shortcut # desktop one-click launch icon
pi-web-ui server quiesce # drain: refuse NEW chats/messages, let running ones finish
pi-web-ui server unquiesce # reopen admissionserver status also shows live stats via a local control socket (version,
PID, quiesce state, connected browsers, running conversations) — the same
socket drives quiesce/unquiesce.
/tmp/pi-web-ui.log / .errsystemctl enable --now), logs via journalctl -u pi-web-ui -fOptions: --port (default 8787), --cwd (workspace), --data-dir (sessions),
--engine <pi|dsh>, --host, --agent-dir, --name (custom service name). Rerunning
server install with new options regenerates the config and restarts the service — that's how
you change its port/cwd/engine. --engine / --host / --agent-dir are baked into the service
automatically; env-only vars (PI_WEB_TOKEN, PI_WEB_DSH_*) must be added to the service config
by hand. See the start flags table above.
pi-web-ui server install --engine dsh --port 9000 --cwd /path/to/projectThe image builds the frontend and the server, keeps the compiler toolchain node-pty needs, pre-installs the DSH runtime (so PI_WEB_ENGINE=dsh works without extra steps), runs as the non-root node user and declares /app/.pi-web as a volume:
docker compose up -d # then open http://localhost:8787docker-compose.yml already sets PI_WEB_HOST=0.0.0.0 (required for port mapping) and persists the data dir in the named volume pi-web-data. The commented blocks in that file cover the usual container tweaks — switching to the DSH engine, mounting a dsh-patches directory, mounting your project as PI_WEB_CWD, and mounting ~/.pi/agent read-only as PI_CODING_AGENT_DIR so the container sees your API keys and model config:
services:
pi-web-ui:
build: .
ports: ["8787:8787"]
environment:
PI_WEB_HOST: 0.0.0.0
# PI_WEB_ENGINE: dsh
volumes:
- pi-web-data:/app/.pi-web
# - ./my-project:/workspace:ro
# - ~/.pi/agent:/root/.pi/agent:ro
volumes:
pi-web-data:Plugins are optional UI components (extra top-bar tabs backed by their own
client view, optionally with a server-side entry and agent tools). They live in
your data-dir plugins folder (<dataDir>/plugins/<id>/, default
~/.pi-web/plugins/) — a plugin is simply a directory containing
manifest.json, an optional server entry (index.mjs) and an optional view
entry (client/entry.mjs). No plugin directories = no plugins, nothing shows
up in the UI.
These plugins ship in this repository (plugins/<id>/) and can be installed
straight from GitHub:
| Plugin | What it does |
|---|---|
| 📬 webmail | IMAP inbox browsing / search / read / mark / delete + SMTP sending, new-mail notifications, and an optional "allow AI to manage my mailbox" switch (six mail_* agent tools). Auto-installs its npm deps on first activation. |
| 🗄️ db-client | Database workbench: connection manager + schema tree for MySQL / PostgreSQL / SQLite / SQL Server / MongoDB / Redis — table structure, paginated data with sorting, SQL editor, and row editing. Drivers auto-install on first use. |
| 📝 vscode-editor | VS Code-like workbench: multi-root file tree (local + SSH hosts), CodeMirror multi-tab editor, Remote-SSH remote file browsing/editing, draggable multi-terminal panel (xterm.js), SFTP sync & upload/download to your computer. Auto-installs ssh2. |
| 📊 mermaid | Renders ```mermaid fences in chat messages as SVG diagrams (fenced-code renderer plugin, offline-first local engine). |
| 🧭 run-trace | Run trajectory: task → thinking → tools → file changes → result timeline with replay and node details. |
| 📖 legado-web | Legado book reader (📖 阅读): search / discovery / book info / TOC / chapter reading on top of Android-compatible book sources, with source import, health checking and dead-source cleanup, and four agent tools (legado_rules, legado_book_sources, legado_source_probe, legado_run_rule) plus an “🤖 AI fix this source” button that opens a new chat with the failure context. Sources/shelf/progress persist under <dataDir>/legado-web/. |
plugins/demo-mailbox stays in the repo as the minimal plugin template (server entry + client view + two-way message protocol) and test fixture — start there if you want to write your own.
Example — install the webmail plugin:
pi-web-ui install https://github.com/xing-shuyin/pi-web-ui/tree/main/plugins/webmailYou can also install from inside the UI: 设置 → 界面插件 → 插件市场 lists
maintainable plugins (the same set, shipped in plugins/catalog.json) with
full 安装 / 更新 / 卸载 controls (updates keep config.json), and lets you
drop any third-party plugin into the list via 添加插件 (paste owner/repo
or an owner/repo/subdir source) — your additions are stored in
<dataDir>/plugin-catalog.json. A plugin author can contribute to the built-in
list with a one-line PR to plugins/catalog.json.
Each plugin's directory in the repo has its own README.md with full feature
lists, configuration and per-plugin caveats.
From GitHub (any of these source forms):
pi-web-ui install owner/repo # shorthand
pi-web-ui install https://github.com/owner/repo # full URL (.git optional)
pi-web-ui install https://github.com/o/r/tree/dev/sub/dir # branch + subdirectory inside the repo
pi-web-ui install owner/repo#v1.2 # pin a branch/tag (#suffix works on any form above)
pi-web-ui install /path/to/plugin-dir # local directory (for development)Useful options:
--name <id> — custom plugin id / directory name (defaults to the repo or
subdirectory name; letters/digits/-/_ only).--force — overwrite an existing installation. Your plugin's local
config.json (credentials etc.) is preserved across upgrades.--data-dir <dir> — override the data dir (default ~/.pi-web).The CLI clones the repo (shallow; falls back to a tarball download without
git), locates the manifest.json (including inside subdirectories) and copies
the plugin into <dataDir>/plugins/<id>/.
No git? No network? You can also just copy a plugin directory into
~/.pi-web/plugins/ by hand — same result.
Re-run install against the same source with --force:
# example: update the webmail plugin to the latest version in the repo
pi-web-ui install https://github.com/xing-shuyin/pi-web-ui/tree/main/plugins/webmail --forceconfig.json automatically.db-connections.json, vscode-editor's ssh-hosts.json) are not covered
by that preservation — back those up before a forced reinstall.pi-web-ui plugins --check-updates compares each plugin's recorded commit against the remote HEAD and prints the exact update command. pi-web-ui plugins --rollback <id> restores the newest pre-upgrade snapshot (every --force install snapshots the old directory into <dataDir>/plugin-backups/, keeping the latest three, and rolls itself back if the copy fails).If the server is running, just refresh the browser — new plugins are picked up on attach without a restart. If it isn't, they load on next start. Each plugin appears as a tab (🧩 or its own icon) in the top bar.
pi-web-ui plugins # list installed plugins (id / name / version / description)
pi-web-ui uninstall <id> # remove a pluginuninstall deletes the plugin directory; refresh the browser and its tab
disappears. Plugin configuration written inside the plugin dir is removed
too — back up <dataDir>/plugins/<id>/config.json first if you need it.Pick elements on the site you are developing and turn them into context an AI can act on, then drop it
straight into the pi-web-ui composer (Alt+Shift+P or the toolbar icon → hover highlight → click to pick
→ Shift+click for multi-select → add a note → "Add to chat").
It is a browser extension, not a pi-web-ui server plugin (so pi-web-ui install does not apply):
Download & install (no Node required): page-picker-extension.zip → unzip →
open chrome://extensions, enable "Developer mode", choose "Load unpacked" and select the unzipped
folder → open the extension options and set your pi-web-ui address (click "Authorize this address"
first for remote/LAN addresses).
See plugins/page-picker/README.md for the interaction details,
what gets captured, remote/LAN setups and known limitations.
It captures what actually lets an AI fix the code in one shot — not a screenshot: the React component
source location from the fiber (Card.tsx:18:5 plus the component chain), the Vue SFC file, the
source file and line of the CSS rules that matched (reverse-computed in Vite dev), a computed-style
subset limited to values that differ from the defaults, a short unique selector, an HTML skeleton and
truncated text. An optional element screenshot rides along as a chat attachment.
Each theme is a pure :root palette override — a small CSS file that only sets CSS variables (see the :root block in web/src/styles.css for the full variable list: base colors --bg/--accent/--term-* plus derived colors like --tooltip-bg/--code-bg/--notice-*). The layout lives ONLY in the bundled web/src/styles.css; picking a theme overrides the variables, so every theme works with every build and layout changes never touch themes. Built-in themes are generated by node make-light-theme.mjs.
Built-in themes ship in the npm package (themes/): white (light), cyberpunk / dazzle (dark), and translucent / transparent (wallpaper-friendly, pair with a chat wallpaper). The theme picker lives in the top bar (🌞 icon); the current choice is stored per browser in localStorage.
Just pick it in the top bar — built-in and user themes are merged in the same menu. User themes win over built-ins on the same id.
Any CSS file dropped into your data-dir themes folder shows up in the theme menu automatically — no restart, no rebuild:
~/.pi-web, override with PI_WEB_DATA_DIR).<dataDir>/themes/ and drop your stylesheet in: e.g. ~/.pi-web/themes/my-theme.css..css) is the theme id shown in the menu.~/.pi-web/
└── themes/
└── my-theme.css # appears in the menu as "my-theme"Easiest way to write one: copy a built-in palette (e.g. themes/white.css from the source repo) and change the :root colors — list every variable you want to override; unlisted ones fall back to the dark defaults in styles.css. Notes:
--term-* variables (terminal ANSI palette + --term-bg) in your :root and both the xterm canvas and its padded container adapt automatically (see the defaults in styles.css).highlight.js's github-dark.css is bundled) must be overridden in your theme file or code will be unreadable on light themes — see the .hljs overrides at the bottom of themes/white.css for the pattern (dark themes can skip it).^[A-Za-z0-9_-]+$ (no dots/slashes — path-traversal guard on the server).Want your theme shipped to everyone? Open a pull request at github.com/xing-shuyin/pi-web-ui:
themes/<id>.css — a pure :root palette. Copy themes/white.css (or themes/cyberpunk.css for a dark palette) as the starting template.npm run dev, then use the top bar theme picker — your theme must be listed and render correctly (chat cards, code blocks, tool-call cards, git/terminal panels).node make-light-theme.mjs when you changed the variable list in styles.css.git add themes/<id>.css) and open the PR. The themes/ folder is already in the npm package files whitelist, so once merged and released, npm i -g pi-web-ui will ship your theme to everyone.Rules for merged themes: the file must be a single CSS file, set the --term-* variables for a readable terminal, and override .hljs syntax colors for readable code on light themes.
All optional — the defaults are what the app is developed against. Full reference: docs/env-vars.md.
| Variable | Default | What it changes |
|---|---|---|
PI_WEB_TOOL_TIMEOUT_MS |
1200000 (20 min) |
Per-tool-call watchdog; a tool still running is aborted (ask_user_question is exempt). |
PI_WEB_STALL_NOTIFY_MS |
180000 (3 min) |
Warn — without aborting — when a streaming run produces no event at all; 0 disables. |
PI_WEB_TERMINAL_IDLE_MS |
15000 |
Nudge the AI when a terminal it opened goes silent for this long; 0 disables. |
PI_WEB_TERMINAL_IDLE_LINES |
10 |
How many trailing terminal lines that nudge quotes back (1–500). |
PI_WEB_INLINE_FILE_MAX |
12288 (12 KB) |
Size under which a path-less uploaded file is inlined instead of referenced. |
PI_WEB_VISION_TIMEOUT_MS |
90000 |
Timeout for one whole vision-bridge transcription batch. |
PI_WEB_UPLOAD_RETENTION_DAYS |
14 |
Retention for <dataDir>/uploads/; 0 never sweeps. |
PI_WEB_SHELL |
auto | Windows only: which shell node-pty spawns (auto: PI_WEB_SHELL → $SHELL → Git Bash → bundled busybox → %COMSPEC% → PowerShell). |
PI_WEB_TABS |
all tabs | Comma-separated tab allow-list (chat,terminal,git,search,tasks,settings,plugins); hidden tabs are refused server-side, chat can't be turned off. |
PI_WEB_MANAGED |
off | 1/true declares the instance externally deployed: self-update, pi-CLI install and plugin installs are refused with a reason and hidden in the UI. |
PI_WEB_ALLOW_HOSTS |
empty | Strict hostname allow-list for the HTTP/WS Host header, on top of the always-on same-authority check. |
PI_WEB_LOCALE |
empty | Fallback UI language for first-time visitors (an explicit choice and the browser's languages win over it). |
PI_WEB_LOCALE_BASE_URL |
GitHub raw | Where language packs are downloaded from — point it at a mirror for offline/intranet installs. |
PI_WEB_PKG_ROOT |
auto | Overrides where the server looks for package.json, themes/, plugins/catalog.json and web/dist (non-standard install layouts). |
PI_CODING_AGENT_SESSION_DIR |
empty | Flat session layout for pi instead of <agentDir>/sessions/--<cwd>--/ (changes what the history list reads). |
DSH_* |
— | DSH runtime knobs: PI_WEB_DSH_RUNTIME, PI_WEB_DSH_DATA_DIR, PI_WEB_DSH_PATCH_DIR, PI_WEB_DSH_QUESTION_TIMEOUT_MS, PI_WEB_DSH_TOOL_TIMEOUT_MS, PI_WEB_DSH_SESSION_RETENTION_DAYS, PI_WEB_DSH_DEBUG. |
127.0.0.1 and is not
reachable from the network unless you explicitly set PI_WEB_HOST=0.0.0.0
(e.g. LAN access, Docker port mapping — the compose file sets it for you)./ws must present
an Origin whose hostname and port match the request Host;
cross-origin pages are rejected with 403. Non-browser clients (no Origin)
are unaffected. Add PI_WEB_ALLOW_ORIGINS=http://your-host:port for
reverse-proxy setups.server quiesce refuses new prompts/forks/session resumes
until you server unquiesce; in-flight runs finish cleanly (useful before
upgrades/backups).headers (which may carry
Authorization / API keys) are never sent to the browser; the model
management UI edits everything else and the server preserves the headers.Free code signing provided by SignPath.io, certificate by SignPath Foundation.
Release binaries — the Windows installer pi-web-ui-desktop Setup <version>.exe
attached to every release —
are built from the tagged commit by
.github/workflows/desktop-release.yml
and signed in that CI run, so a valid signature means the file is an automated
build of the source code at that tag.
| Role | Who |
|---|---|
Authors / committers (may push to main) |
@xing-shuyin |
| Reviewers (every non-committer change arrives as a PR and is reviewed before merge) | @xing-shuyin — community contributions are credited in the contributors graph |
| Approvers (must approve each signing request) | @xing-shuyin |
All team members use multi-factor authentication for both GitHub and SignPath. Our release artifacts contain no binaries we did not build ourselves, except upstream open-source components bundled by npm and electron-builder (see License).
Privacy policy: see Privacy below.
pi-web-ui runs entirely on your own machine and has no telemetry, no analytics
and no accounts of its own. Conversations, attachments, settings and terminal
history stay on your disk: chat transcripts in the pi agent dir
(~/.pi/agent/sessions/ by default), everything else (UI settings, recent
projects, plugins, uploads, themes, language packs) in the data dir
(~/.pi-web/, or %APPDATA%\pi-web-ui\data for the desktop app). The HTTP
server binds loopback unless you explicitly expose it.
Network requests happen only in these cases:
| When | To | What leaves your machine |
|---|---|---|
| You send a message, or the agent calls a model | the model providers you configure (e.g. api.openai.com, api.opencode.ai, a local endpoint) |
your prompt, the attached file contents and the conversation context |
| Model catalog refresh (startup, then every 4 h) | pi.dev |
nothing but the request itself |
| You install or update a plugin, theme or language pack | github.com / raw.githubusercontent.com |
nothing but the request itself |
| You check for or install an update | registry.npmjs.org |
nothing but the request itself |
Terminals on Windows, when neither Git Bash nor a bash on PATH exists |
frippery.org |
one download of busybox64u.exe into ~/.pi-web/bin/bash.exe, reused offline afterwards |
Reverse-proxy setups, the optional PI_WEB_TOKEN password and Docker port
mappings are under your control — see Security.
Serve pi-web-ui behind nginx on the same host (it binds loopback only, so a
same-machine reverse proxy is the supported remote-access path — no
PI_WEB_HOST=0.0.0.0 needed):
# pi-web-ui on 127.0.0.1:8787, exposed as https://your-host/pi/
server {
listen 443 ssl;
server_name your-host;
# ssl_certificate ... / ssl_certificate_key ...
# App entry at a sub-path (strips the /pi/ prefix)
location /pi/ {
proxy_pass http://127.0.0.1:8787/;
proxy_http_version 1.1;
# $http_host keeps the port — the server's origin check compares the
# full authority (hostname AND port). $host would drop it and get 403.
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# WebSocket — MUST forward Host identically or the upgrade is 403'd
# (page loads, but chat/terminal keep reconnecting)
location /ws {
proxy_pass http://127.0.0.1:8787;
proxy_http_version 1.1;
proxy_set_header Host $http_host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}
# Absolute-path assets/API the built frontend requests (root, not /pi/)
location /assets/ { proxy_pass http://127.0.0.1:8787; }
location = /favicon.svg { proxy_pass http://127.0.0.1:8787; }
location = /api/file { proxy_pass http://127.0.0.1:8787; }
location = /api/health { proxy_pass http://127.0.0.1:8787; }
}Key points:
Host must be $http_host (keeps the port) on both /pi/ and /ws —
the origin check compares hostname and port. proxy_set_header Host $host
or leaving it unset (defaults to the upstream 127.0.0.1:8787) both fail with 403.Origin equals
the forwarded Host (it does through a plain proxy), no
PI_WEB_ALLOW_ORIGINS is needed. Only set it when the browser origin differs
from the Host the server sees (e.g. a TLS-terminating proxy that changes the
port).proxy_protocol unless you really need real client IPs: it makes
nginx reject every connection that does not send a PROXY header, which
breaks direct LAN access and any non-frp clients. With frp, drop
transport.proxyProtocolVersion from the proxy config unless nginx listens
with proxy_protocol too.PI_WEB_HOST=0.0.0.0 (and a
firewall rule) — or put the whole server block above on port 80/443.Full working example (with an frp tunnel): deploy/nginx-subpath.conf.
pi-web-ui is a small open-source project — your contributions are what make it grow. Code, plugins, themes, docs, translations, ideas: everything is welcome, and every merged PR ships to all users with the next npm publish. ❤️
| Way to contribute | How to get started |
|---|---|
| 🧩 Write a plugin | Build your own UI tab + agent tools. Copy plugins/demo-mailbox as the minimal template (it doubles as the test fixture), develop locally, then either open a PR to ship it in the catalog or publish it standalone. |
| 🎨 Contribute a theme | Copy themes/white.css (light) or themes/cyberpunk.css (dark) as a pure-palette template, tweak the :root palette + --term-* + .hljs, verify with npm run dev, then open a PR — full walkthrough in Contributing a theme. |
| 💻 Fix a bug / add a feature | Look for open issues or propose something new. Fork → branch → PR. Keep the code conventions in AGENTS.md (tabs, i18n keys in both languages, protocol changes in server/protocol.ts). |
| 📖 Docs & translations | Improve the READMEs, write plugin docs, fix typos, or help translate the UI / docs into more languages. |
| 💡 Ideas & feedback | Open an issue or start a discussion — feature requests, bug reports, UI polish ideas, deployment experience reports. |
Before opening a PR, a quick sanity pass keeps reviewers happy:
npm run format — prettier formatting (tabs, width 120; CI checks it).npm run lint — oxlint (unused vars, risky patterns; CI runs it).npm run check:protocol + npm test — protocol sync and unit tests.npm run typecheck — no type errors.npm run build — both frontend and backend compile.server/index.ts and web/src/use-chat.ts (see the "Protocol single source" note in AGENTS.md).Enjoying pi-web-ui? Give the repo a ⭐ — it helps others find it. And if you built something cool on top (plugin, theme, deployment recipe), tell us — we love showcasing community work.
CLASSIFICATION EVIDENCE
系统优先读取 GitHub Topics，再与站内分类词典和词根规则比对。当前命中： pi-web-ui。
zhu1090093659
DeepSeek Harness (DSH) Web 插件聚合生态 · 万物皆插件，通过创意工坊分发｜｜DeepSeek Harness (DSH) Web Plugin Aggregation Ecosystem · Everything is a plugin, distributed via the Creative Workshop
omdsh-dev
开放的侧边栏底座，支持三方拓展注册新侧边栏页面。内置文件渲染编辑/终端/侧边对话/Git/子代理页面 ｜ Open sidebar foundation, supports third-party extensions to register new sidebar pages. Built-in file rendering/editing, terminal, side chat, Git, and sub-agent pages.
Devin-AXIS
DeepSeek Harness 可编辑设计系统：AI 生成、可视化编辑、模板市场与 PPT｜Native Design & PPT Studio for DeepSeek Harness.