sPi - Simple Pi Agent GUI

Lightweight Pi package and desktop installer. Desktop binaries are downloaded from the matching GitHub Release, not included in this npm package. No AppImage, FUSE, native compilation or second copy of Pi is required.

The npm package name is spi-agent-gui. Install with pi install npm:spi-agent-gui, then run spi. Automatic installation supports Linux x64 and arm64. Supplemental manual Mac Apple Silicon/Intel ZIPs are available in desktop Releases; they are ad-hoc signed, not Developer ID signed or notarized. Mac ZIPs are not automatic installer targets. Windows distribution remains deferred. The package registers /spi and /spi-install; it never launches a GUI just because an extension was loaded. Project/temporary/CI installs and SPI_SKIP_INSTALL=1 skip automatic system-wide side effects. If lifecycle scripts are disabled, use /spi-install or explicitly run npx --package spi-agent-gui spi install.

Runtime downloads show percentage, received/total MiB and average speed every 10 seconds, including when interactive npm buffers its postinstall output. A healthy slow transfer has a one-hour overall budget, with a separate 60-second inactivity limit and up to three validated Range/If-Range attempts. The complete archive size/SHA-256 is always verified; prior runtime selection is preserved on failure. SPI_DOWNLOAD_TIMEOUT_SECONDS accepts 60–21600 seconds. Resume applies within one install, not across processes; no permanent cache is implied. Headless log capture can use npm_config_foreground_scripts=true for that command.

If sessions cannot start because desktop PATH differs from your terminal, sPi detects compatible Node from PATH, Pi-managed runtime or login shell. Settings → Node.js runtime also accepts an optional absolute Node executable path, checked before private saving; clear it for automatic lookup. It applies to new/reopened sessions without restarting existing ones or changing Pi/shell configuration.

Desktop 0.2.0 adds optional end-to-end encrypted remote access: a window on one computer can drive sPi on another, relayed through Microsoft Dev Tunnels. It requires the GitHub CLI (gh) signed in to the same GitHub account on both computers; local use never needs gh. In 0.3.0, only one remote connection has control (including terminals), while others are read-only. The oldest connected viewer takes over when the controller disconnects or is revoked. Remote protocol v2 requires both computers to update together; saved pairings are retained. Remote access.

Desktop 0.3.0 also adds a visible pending/paired device list: close Settings and return later to view the same pending pairing code; devices save automatically after pairing. One pending invitation at a time, in memory only; restarting invalidates it. Pairing codes default to 1 hour, configurable up to 60 days. Floating Previous/Next question arrows beside the chat scrollbar jump through your own inputs without scrolling through long outputs; navigating history pauses auto-follow until Return to latest.

Desktop 0.1.5 added passive send-triggered RPC checks and explicit recovery, terminal visibility and clipboard context menus, manual/current-model AI session names, confirmed history trash and restored window placement/maximization. AI names are suggestions to review before saving; they incur a normal model request but run no tools and do not add chat entries. Recovery keeps the outbox paused and never blindly replays work. Save important drafts and fully quit the old GUI before reopening; installation does not hot-update a running window. Feature details.

spi --help, spi doctor, spi update, spi rollback, spi uninstall. Use --bin-dir if Pi's PATH directory is not writable or another spi command exists. No shell profile is edited. User preferences and Pi sessions survive uninstall. pi remove removes this package, not the independently installed desktop runtime.

The installer requires Node.js 22.19+; the installed command can use its private Electron runtime's Node mode. Supported platforms are only those present in the verified Release manifest. Unsigned Windows/macOS binaries may trigger OS warnings; do not disable OS protections. Linux needs a glibc desktop environment.