How jmfederico/pi-web works
PI WEB is a browser control surface for persistent Pi Coding Agent sessions running in real workspaces on local or remote machines. The principal flow is to select a machine, create or choose a project and workspace, start a session, and supervise the agent; sessions continue when the browser disconnects. The product also exposes workspace files, terminals, Git, plugins, and remote-machine resources. The README supports these capability-level relationships; sampled source confirms workspace file routing, preview handling, and federation details, but not every subsystem’s internal wiring.
Main entry points: app.ts HTTP server · api.ts Client API · workspaceExplorerRoutes.ts Workspace file routes · piSessionService.ts Session service
Components 24
Browser control
- Web interface
src/client/src/main.ts - Client API
src/client/src/api.ts - Machine controls
src/client/src/controllers/machineController.ts - Workspace browser
src/client/src/components/WorkspacePanel.ts - Session controls
src/client/src/controllers/sessionController.ts
Machine runtime
- HTTP server
src/server/app.ts - Machine service
src/server/machines/machineService.ts - Machine registry
src/server/machines/machineStore.ts - Daemon client
src/sessiond/sessionDaemonClient.ts - Session daemon
src/server/sessiond.ts
Projects and files
- Project management
src/server/projects/projectService.ts - Workspace catalog
src/server/workspaces/workspaceCatalog.ts - Workspace file routes
src/server/workspaceExplorerRoutes.ts - File preview
src/server/workspaces/filePreviewService.ts
Agent sessions
- Session routes
src/server/sessions/sessionRoutes.ts - Session service
src/server/sessions/piSessionService.ts - Session archive
src/server/sessions/sessionArchiveStore.ts
Tools and federation
- Terminal plugin
pi-web-plugins/terminal/pi-web-plugin.ts - Git plugin
pi-web-plugins/git/browser/pi-web-plugin.ts - Plugin lifecycle
src/server/piWebPluginLifecycle.ts - Remote machine proxy
src/server/machines/machineProxyRoutes.ts
Other components
- Developer
- Pi Coding Agent
- Remote PI WEB
Connections 28
- Developer → Web interface: controls
- Web interface → Client API: requests
- Client API → HTTP server: calls API
- Web interface → Machine controls: selects machine
- Machine controls → Machine service: manages
- Machine service → Machine registry: reads and writes
- HTTP server → Project management: routes project work
- Project management → Workspace catalog: resolves workspaces
- Workspace browser → Client API: requests files
- HTTP server → Workspace file routes: registers routes
- Workspace file routes → Workspace catalog: resolves context
- Workspace file routes → File preview: reads previews
- Workspace file routes → Workspace browser: returns file data
- Session controls → Client API: starts sessions
- HTTP server → Session routes: routes sessions
- Session routes → Session service: dispatches
- Session service → Daemon client: uses daemon
- Daemon client → Session daemon: sends requests
- Session daemon → Pi Coding Agent: runs agent
- Session service → Session archive: archives sessions
- Session service → Session controls: streams session updates
- Developer → Workspace browser: browses workspace
- Developer → Terminal plugin: uses terminal
- Developer → Git plugin: reviews Git
- HTTP server → Plugin lifecycle: manages plugins
- Remote machine proxy → Remote PI WEB: proxies requests
- HTTP server → Remote machine proxy: routes federated calls
- Client API → Remote machine proxy: targets selected machine