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 + build (tsc)
make start      # run the server
make test       # build + run tests

configuration

command-line flags:

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

environment variables:

| variable | default | purpose | | --- | --- | --- | | PI_WEBUI_HOST | 127.0.0.1 | http bind address | | PI_WEBUI_PORT | 4096 | http 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
HOST=0.0.0.0 PORT=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.

roadmap

see ROADMAP.md for implemented and planned features.

architecture

src/
  extension/   pi extension entry (slash command + auto-start flag)
  server/      http + websocket server hosting the pi sdk runtime
                 index.ts, event-log.ts, log.ts, watch.ts, ext-ui.ts
public/        browser client (vanilla js, no build step)
test/          node --test files

development

make            # install deps + build (tsc)
make start      # run the server
make install    # install pi-webui globally from this checkout
make update     # update dependencies (npm update)
make test       # build + run tests
make lint       # tsc --noEmit + node --check on .mjs sources
make precommit  # lint + test
make vendor     # refresh public/vendor (marked, highlight.js)
make clean      # rm -rf dist build