pi-gui/README.md

Pi Status Bridge

A local Unix-socket bridge and desktop UI for monitoring and controlling persistent Pi coding-agent sessions without bypassing Pi-owned safety policy.

Pi Status Bridge keeps one Pi RPC agent per selected worktree, exposes a local-only protocol, and provides desktop and Noctalia adapters. It is experimental software: use it on worktrees you control and verify the documented security boundaries before daily use.

What it provides

• A local bridge that owns Pi RPC child processes, sessions, recovery, and worktree routing.
• A same-user Unix-domain socket; it never listens on TCP.
• A Tauri + React desktop client for agents, transcripts, prompts, model/thinking controls, and extension requests.
• Presentation-only adapters for Noctalia v4 and v5.
• A local client CLI for request/response and event subscriptions.
• Bounded recovery for unexpected Pi child exits.

Requirements

• Node.js 20 or newer.
• A working pi command available on PATH; the bridge starts Pi with pi --mode rpc.
• Linux or another Unix-like environment with an absolute XDG_RUNTIME_DIR.
• For the desktop UI: Rust stable and the native prerequisites required by Tauri v2.
• For Noctalia integration: a compatible Noctalia v4 or v5 installation.

Quick start

Clone the repository and install the desktop UI dependencies:

git clone ssh://git@git.commumedia.org:2222/alex/pi-gui.git
cd pi-gui
npm --prefix ui ci

Start the bridge for your home worktree. XDG_RUNTIME_DIR must already be set by the desktop session.

node src/bridge/cli.js \
  --worktree "$HOME" \
  --session-root "$HOME/.local/state/pi-status-bridge/sessions"

The bridge prints its socket path as JSON. In another terminal, start the desktop client:

npm --prefix ui run tauri dev

The desktop client reads PI_STATUS_BRIDGE_SOCKET when set; otherwise it uses $XDG_RUNTIME_DIR/pi-status-bridge/bridge.sock.

CLI usage

Bridge daemon

node src/bridge/cli.js [--worktree <path>] [--runtime-dir <absolute-path>] [--session-root <path>]

• --worktree defaults to the current user's home directory.
• --runtime-dir overrides XDG_RUNTIME_DIR; it must be absolute.
• --session-root selects where the bridge stores Pi session references.

Local client

Use the printed socket path or export it once:

export PI_STATUS_BRIDGE_SOCKET="$XDG_RUNTIME_DIR/pi-status-bridge/bridge.sock"
node src/client/cli.js request '{"op":"list_agents"}'
node src/client/cli.js subscribe --agent <agent-id>

The request payload is the local protocol JSON. See DESIGN.md for the architectural contract and specs/FULL_PI_PANEL_SPEC.md for the desktop surface.

Noctalia relay

node src/client/noctalia-relay-cli.js \
  --socket "$PI_STATUS_BRIDGE_SOCKET" \
  --agent <agent-id>

Install the adapter that matches your desktop: noctalia-plugin/ supports v4 and noctalia-v5-plugin/ supports v5. Both adapters are presentation-only; neither starts Pi nor approves extension requests.

Keep the bridge running in the background (recommended)

The desktop UI connects on demand; only the bridge needs to run persistently. On Linux systems using systemd, install the bridge command globally once, then use the included user service:

npm install --global .
command -v pi-status-bridge pi
npm run bridge:service:install

The npm commands below are short, copyable wrappers around systemctl --user:

npm run bridge:service:start    # start the bridge
npm run bridge:service:restart  # apply bridge changes or recover it
npm run bridge:service:stop     # stop the bridge
npm run bridge:service:status   # check whether it is healthy
npm run bridge:service:logs     # follow bridge logs; Ctrl+C returns to the shell

If systemd cannot locate either executable, add a user-service drop-in that sets PATH to their containing directories; do not hard-code another user's home path in the tracked unit.

Opening the desktop UI

• Development: run npm --prefix ui run tauri dev in a terminal after starting the bridge.
• Installed UI: launch it from your application menu or run pi-status-ui --toggle. The --toggle command shows a hidden window or hides a visible one; it does not restart the bridge.
• Noctalia: use the Pi Status launcher as usual; it opens the installed UI.

Restart Pi in the UI restarts only the selected directory's Pi agent. npm run bridge:service:restart restarts the whole bridge service and all of its active agents.

Development

# Bridge and protocol tests, then Tauri tests
npm test

# JavaScript syntax checks and production UI build
npm run check

# Desktop UI only
npm --prefix ui run dev
npm --prefix ui run tauri dev

npm test is the repository acceptance command. It runs the Node test suite and the Tauri Rust tests. npm run check additionally builds the UI.

Architecture and documentation

• docs/README.md — documentation index.
• DESIGN.md — system boundaries and security invariants.
• IMPLEMENTATION_PLAN.md — implementation milestones.
• TEST_PLAN.md — automated, manual, and soak-test acceptance criteria.
• specs/ — detailed UI and Tauri architecture specifications.

Contributing

Read CONTRIBUTING.md before opening a change. Keep prompts and worktree routing explicit, preserve local-only transport, and run both verification commands before review.

Security

Read SECURITY.md before deployment or vulnerability reporting. The bridge must never introduce a network listener or bypass Pi extension approvals.

License

Copyright 2026 Alex Blank. Licensed under the Apache License 2.0.