pi-gui/README.md

# Pi Status Bridge

> A local Unix-socket bridge and desktop UI for monitoring and controlling persistent [Pi](https://github.com/badlogic/pi-mono) 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](https://v2.tauri.app/start/prerequisites/).
- For Noctalia integration: a compatible Noctalia v4 or v5 installation.

## Quick start

Clone the repository and install the desktop UI dependencies:

```bash
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.

```bash
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:

```bash
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

```bash
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:

```bash
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`](DESIGN.md) for the architectural contract and [`specs/FULL_PI_PANEL_SPEC.md`](specs/FULL_PI_PANEL_SPEC.md) for the desktop surface.

### Noctalia relay

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

Install the adapter that matches your desktop: [`noctalia-plugin/`](noctalia-plugin/) supports v4 and [`noctalia-v5-plugin/`](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:

```bash
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`:

```bash
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

```bash
# 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`](docs/README.md) — documentation index.
- [`DESIGN.md`](DESIGN.md) — system boundaries and security invariants.
- [`IMPLEMENTATION_PLAN.md`](IMPLEMENTATION_PLAN.md) — implementation milestones.
- [`TEST_PLAN.md`](TEST_PLAN.md) — automated, manual, and soak-test acceptance criteria.
- [`specs/`](specs/) — detailed UI and Tauri architecture specifications.

## Contributing

Read [`CONTRIBUTING.md`](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`](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](LICENSE).