PUI — Pi as a Modern Harness App

Pi harness as a modern browser app, with UI, web search, subagents, /goal, and more

/ˌpiː juː ˈaɪ/

PUI turns the vanilla Pi harness into a modern browser-based AI workspace, similar to Claude Code, Codex, or OpenCode Desktop. It adds a UI, web search, subagents, /goal, and more, all installed in one command.

Pi is a great harness, one of the most efficient on the market. But it's minimalistic by nature, so you don't get a desktop app experience out of the box. PUI solves this by composing open-source projects from the Pi ecosystem at setup time. It adds no PUI runtime process and does not maintain a Pi fork.

Features

Use Pi from a browser. Pi Web provides the local GUI. PUI configures it at http://127.0.0.1:30141 and can start it automatically for the current user.
App-like use via PWA. To use PUI as an application, open it in a browser and install is as a PWA. This requires user action, so the installer can't do this automatically.
Research the web without API keys. pi-web-access routes web_search through anonymous Exa and DuckDuckGo, while fetch_content uses direct HTTP requests.
Split work with subagents. @gotgenes/pi-subagents adds in-process subagents for parallel work.
Drive the session toward a goal. @narumitw/pi-goal adds a session-scoped /goal mode.
Automate the browser with Playwright. PUI configures @playwright/mcp through pi-mcp-adapter for lazy, headless Chrome automation.
Keep the CLI and browser in the same Pi environment. PUI aligns standalone Pi with the agent runtime bundled by Pi Web, uses Pi's normal ~/.pi/agent configuration, and enables Pi's standard local tools by default.
Install and maintain the composition as one profile. The lifecycle scripts back up JSON before changing it, structurally merge only PUI-owned settings, reconcile managed packages, reapply branding after updates, and preserve user-owned configuration during uninstall.

PUI screenshot

Requirements

Windows 10 or 11, macOS, or Linux
Node.js 22.19.0 or newer (node --version)
npm, which is bundled with Node.js
Git
curl on Linux
Chrome for the configured Playwright MCP server
systemd on Linux only when using the default autostart setup

PUI does not install Node.js, Git, or Chrome. When PWA integration is enabled, it creates a per-user autostart entry: a Startup-folder launcher on Windows, a LaunchAgent on macOS, or a systemd user service on Linux. The prerequisite check stops before setup if a required command is missing or Node.js is too old.

Install

Open a terminal in this repository, then run the platform entry point. Or ask your agent to do so.

Windows (PowerShell):

./install.ps1

macOS or Linux:

./install.sh

Before changing an existing JSON configuration file, the installer creates a timestamped backup. Invalid JSON stops setup safely. For JSON merges, unrelated settings are preserved and PUI manages only the fields and package entries described in stack.json.

Options

Option	Effect
`-NoPwa` / `--no-pwa`	Skip autostart and the browser app-setup page. Pi Web remains installed; start it manually with `pi-web`.
`-NoBrowser` / `--no-browser`	Configure autostart but do not open the app-setup page after installation.
`-KeylessRoute` / `--keyless-route`	Make PUI's keyless route primary when another primary search provider exists. The other provider remains configured after it. Without this option, the conflict stops installation for an explicit choice.
`-UnpinPuiPackages` / `--unpin-pui-packages`	Remove explicit version pins from PUI-managed Pi packages so setup can install current releases. Without this option, existing pins are preserved and reported.

Update, diagnose, and uninstall

PowerShell:

./update.ps1
./doctor.ps1
./uninstall.ps1

macOS or Linux:

./update.sh
./doctor.sh
./uninstall.sh

Update refreshes Pi Web, aligns standalone Pi to Pi Web's bundled runtime, reconciles managed packages, updates extensions and models, reapplies branding and icons, restarts autostart when configured, and runs diagnostics.
Doctor reports component, configuration, autostart, and health status without changing the installation.
Uninstall removes PUI-owned integration and restores original Pi Web assets when available. Add -Full / --full to also remove managed packages, Pi Web, and standalone Pi. User projects, sessions, authentication, skills, and unrelated settings are preserved. A browser-installed PWA must be removed manually from the browser's app or shortcut settings.

Platform details are in Windows, macOS, and Linux. The component reference describes ownership boundaries and managed files.

Credits

PUI is a setup and composition layer built on the work of other open-source projects. Its runtime capabilities come from the maintainers and contributors of the projects below. Thank you to everyone who builds, documents, reviews, and maintains them.

Upstream project	Role in PUI
`@earendil-works/pi-coding-agent`	Base Pi agent runtime used by the CLI and Pi Web
`@agegr/pi-web`	Local browser GUI and PWA entry point
`@gotgenes/pi-subagents`	In-process subagent extension
`pi-web-access`	Web search and direct HTTP fetching
`pi-mcp-adapter`	MCP configuration and proxy integration
`@playwright/mcp`	Browser automation through headless Chrome
`@narumitw/pi-goal`	Session-scoped goal mode

Please see each upstream repository for its license, contribution history, and project-specific terms.

License

PUI is released under the MIT License. Upstream components retain their own licenses.

Back to projects