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.

Run as a user service

The included systemd/pi-status-bridge.service is a portable user-service example. Install the bridge CLI, then ensure both pi-status-bridge and pi are on the user service's PATH:

npm install --global .
command -v pi-status-bridge pi

mkdir -p ~/.config/systemd/user
cp systemd/pi-status-bridge.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now pi-status-bridge.service
systemctl --user status pi-status-bridge.service

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.

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.