pi-webui

a simple, standalone webui for pi.dev

getting started

prerequisites:

• node.js 20+
• a working pi installation

install as a pi extension:

pi install npm:@khimaros/pi-webui

control from the pi tui:

> /webui start    # start the server
> /webui status   # view server status
> /webui open     # open webui in browser
> /webui stop     # stop the server

or auto-start when pi launches (server is terminated when pi exits):

pi --webui                              # start with defaults
pi --webui-listen 0.0.0.0:3000          # start with a custom bind address

run without installing:

npx @khimaros/pi-webui

or install globally:

npm install -g @khimaros/pi-webui
pi-webui

then open http://127.0.0.1:4096.

from a source checkout

make            # install deps + compile the server to dist/ (tsc)
make start      # run the server
make test       # build + run tests

make compiles the server to dist/ with tsc; the standalone pi-webui bin is the emitted dist/server/index.js, run with plain node (node >= 20). a build is required because node refuses to type-strip .ts files under node_modules/, so an installed bin must ship as javascript. the pi extension is the exception: pi loads it through its bundled jiti loader, which transpiles .ts on the fly with no such restriction, so the extension ships and loads as .ts source (src/extension/index.ts) and is never compiled.

configuration

command-line flags:

flag	purpose
--listen <host:port>	http bind address; takes precedence over PI_WEBUI_LISTEN. use :port for default host, or [::1]:port for ipv6.

environment variables:

variable	default	purpose
PI_WEBUI_LISTEN	127.0.0.1:4096	http bind address (host:port, :port, or port)
PI_PROJECT_CWD	process.cwd()	project directory used for sessions
PI_AGENT_DIR	pi default (~/.pi/agent)	pi agent config directory
PI_SESSION_DIR	pi default	session storage directory
PI_WEBUI_CWD_ALLOW_ANY	0	allow /cwd to switch to paths outside $HOME

examples:

pi-webui --listen 0.0.0.0:3000
PI_WEBUI_LISTEN=0.0.0.0:3000 PI_PROJECT_CWD=/path/to/project npm start

attachments

paste images into the composer (Ctrl/Cmd+V) or drag and drop them onto the window. thumbnails appear above the input and ride along with the next prompt. up to 8 images per turn, 10 MB each. PNG, JPEG, GIF, and WebP are accepted.

queued messages

sending a message while the agent is still responding queues it as a follow-up that runs after the current turn, rather than cancelling the turn. queued messages appear dimmed at the bottom of the log and are sent in order as the agent finishes. to stop the current turn instead, press Esc, or send with an empty composer (the send button shows a stop icon when the composer is empty).

roadmap

see ROADMAP.md for implemented and planned features.

architecture

src/
  extension/   pi extension entry (slash command + auto-start flag), shipped as .ts
                 index.ts -- spawns the bin, handshakes on base_url=
  server/      http + websocket server hosting the pi sdk runtime, compiled to dist/
                 index.ts (standalone entrypoint), event-log.ts, log.ts,
                 watch.ts, ext-ui.ts, hub.ts
public/        browser client (vanilla js, no build step)
test/          node --test files (.mjs) + python e2e (fake_openai_test.py)

the server compiles to dist/ (the bin runs under plain node, which will not type-strip .ts under node_modules/); the extension stays .ts and is loaded by pi's jiti loader.

development

make                # install deps + compile the server to dist/ (tsc)
make start          # run the server
make install        # install pi-webui globally from this checkout (onto PATH)
make update         # update dependencies (npm update)
make test           # build + run tests
make test-integration  # black-box python e2e against fake-openai
make lint           # tsc --noEmit + node --check on .mjs sources
make precommit      # lint + test + test-integration
make vendor         # refresh public/vendor (marked, highlight.js)
make clean          # rm -rf dist build