pix
A local web workstation for the pi coding agent.
Your sessions live in a resident daemon, not in a browser tab. Close the window, restart the web server, put your laptop to sleep — running agents keep working, and you reconnect from any browser or from the pix PWA on your phone. Sessions are stored as plain JSONL under ~/.pi, fully shared with the pi CLI: start a conversation in pix, continue it from the terminal, or vice versa.
Why pix
- Sessions that don't die with the tab. The web UI is just a window onto a resident session daemon; refreshes and restarts never kill a running agent.
- History browsing costs nothing. Reading past sessions is a pure read-only projection — no worker processes spin up until you interact.
- Live, structured runtime. Thinking, tool calls, bash output and file edits stream over WebSocket as typed events, with snapshots resuming exactly where you left off.
- Real workspace context. Browse files, git status and worktrees for the session's project without leaving the UI.
- Installable PWA. The same client installs to your phone's home screen and talks to your machine over your own network.
Quick start
Requires Node.js ≥ 22.19 and a working pi setup (models and providers come from your existing ~/.pi configuration).
npm install -g @fffattiger/pix-cli
pix start
pix start serves the pix UI at http://127.0.0.1:30141 (add --open to launch your browser). It stays attached to the terminal — Ctrl+C stops the web host while sessions keep running — which is also how service managers (systemd, launchd, Docker) should run it. Useful flags:
pix start --port 30142 --hostname 0.0.0.0 --open
pix start --detach # run the web host in the background and return once it is ready
To manage the running services:
pix status # sessiond + background host state, URL and log path
pix logs --follow # background host output
pix restart # restart the background host; sessions keep running
pix stop # stop the background host; sessions keep running
pix stop --all # also stop the session daemon (ends running sessions)
pix down --all # stop the session daemon only
pix restart --all also restarts the session daemon, and pix update --restart relaunches a background host on the new version.
Windows (preview)
pix runs on Windows 10/11 with the same commands (npm install -g @fffattiger/pix-cli, then pix start in PowerShell or Windows Terminal). The session daemon uses a per-user named pipe instead of a Unix socket and keeps its state under your user profile. Windows support is a preview: startup is verified on real Windows runners, while parts of the unit-test suite are still being hardened for Windows. See docs/windows.md.
How it works
Browser / PWA
│
Web process — Vite static client + Hono API/WS gateway (restartable)
│ localhost RPC
pix-sessiond — resident daemon, sole session authority
│
agent-worker × N — one process per session
│ AgentRuntimePort
pi SDK (via the anti-corruption layer)
The web process is disposable by design; pix-sessiond owns session lifecycle, and each session runs in its own worker process. All durable state stays in ~/.pi. The full architecture, invariants and package layout are documented in docs/refactor-architecture.md and AGENTS.md.
Development
npm install
npm run check:architecture # package-boundary and tooling gates
npm run typecheck
npm test
npm run build
End-to-end suites (build first): npm run test:e2e:startup, test:e2e:runtime, test:e2e:sessions, test:e2e:lifecycle-sdk, test:e2e:lifecycle-browser, test:e2e:multi-tab.
For a release, update the root version and the Protocol product build version, then synchronize workspace versions and internal dependencies:
node scripts/sync-version.mjs write
npm run release:verify -- --publishable --keep
This creates a standalone archive and a smaller -npm.tgz distribution in an
isolated temporary directory. The standalone checks cover offline installation,
runtime startup, state retention across an upgrade, and uninstall behavior.
The npm archive bundles Pix, Pi's coding-agent SDK, and the patched plugin;
npm installs their external dependencies normally. The SDK 1.0.0 bundle omits
its defective published shrinkwrap. Test the npm archive with a fresh npm
install, then publish it with npm publish <archive-npm.tgz> --access public. Neither the script nor
workspace directories publish a release automatically.
License
Project licensing has not yet been decided. Third-party visual assets and their MIT attribution are documented in THIRD_PARTY_NOTICES.md.