---
slug: "jademind-pi-bridge"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/jademind/pi-bridge@main/README.md"
repo: "https://github.com/jademind/pi-bridge"
source_file: "README.md"
branch: "main"
---
# @jademind/pi-bridge

> Package scope: use `@jademind/pi-bridge` (scoped). Older unscoped naming should be considered deprecated.

Minimal secure inbox bridge for Pi sessions.

`@jademind/pi-bridge` is designed for status bar and mobile clients that must send messages reliably to running Pi agents, including plain terminal sessions where tty injection is unreliable.

It is primarily consumed by the free open-source macOS app [`pi-statusbar`](https://github.com/jademind/pi-statusbar), and complements [`@jademind/pi-telemetry`](https://github.com/jademind/pi-telemetry) for runtime observability.

---

## Related projects

- [`pi-statusbar`](https://github.com/jademind/pi-statusbar): macOS menu bar app for Pi (daemon + UI)
- [`@jademind/pi-telemetry`](https://github.com/jademind/pi-telemetry): per-process telemetry heartbeat + snapshot CLI

## What it does

- Watches a per-PID inbox directory
- Validates signed/structured message envelopes
- Delivers to Pi using user-message semantics
  - queued mode -> `followUp` when busy
  - interrupt mode -> `steer` when busy
- Writes delivery acknowledgements per message
- Publishes lightweight per-session registry heartbeat
- Enforces size limits, TTL, path safety, idempotency, and rate limits

## Install

```bash
pi install npm:@jademind/pi-bridge
```

Restart active Pi sessions after install so the extension loads.

If you use `pi-statusbar`, install/start everything with:

```bash
brew install jademind/tap/pi-statusbar
statusbar-setup enable
```

## Filesystem layout

Default base directory:

```text
~/.pi/agent/statusbridge/
  registry/<pid>.json
  inbox/<pid>/<message-id>.json
  processing/<pid>/*.processing
  acks/<pid>/<message-id>.json
```

Override base with:

- `PI_BRIDGE_DIR`

## Envelope (`send-v1`)

```json
{
  "v": 1,
  "id": "4a4c5295-d3e4-4f91-b562-8f0f4cc6f413",
  "pid": 12345,
  "text": "Please summarize current progress and blockers.",
  "source": "statusbar",
  "createdAt": "2026-02-24T15:50:00Z",
  "expiresAt": "2026-02-24T15:51:00Z",
  "delivery": {
    "mode": "queued"
  },
  "meta": {
    "requestId": "ios-123"
  }
}
```

`delivery.mode` values:

- `queued` (default): queue politely if busy
- `interrupt`: steering interrupt if busy

## Ack (`ack-v1`)

```json
{
  "v": 1,
  "id": "4a4c5295-d3e4-4f91-b562-8f0f4cc6f413",
  "pid": 12345,
  "status": "delivered",
  "at": 1771948234000,
  "resolvedMode": "queued"
}
```

Possible statuses:

- `delivered`
- `failed`
- `duplicate`

## Security defaults

- file size cap: 32 KB
- message length cap: 4000 chars
- strict PID matching
- TTL expiry enforcement
- symlink and path traversal rejection
- bounded queue depth
- separate normal/interrupt rate limiters

## Runtime config

- `PI_BRIDGE_MAX_TEXT` (default `4000`, minimum `256`)
- `PI_BRIDGE_MAX_SKEW_MS` (default `120000`)
- `PI_BRIDGE_HEARTBEAT_MS` (default `2000`)
- `PI_BRIDGE_SCAN_MS` (default `750`)
- `PI_BRIDGE_QUEUE_DEPTH` (default `64`, minimum `8`)
- `PI_BRIDGE_RATE_PER_MIN` (default `20`, minimum `20`)
- `PI_BRIDGE_RATE_BURST` (default `6`, minimum `4`)
- `PI_BRIDGE_INTERRUPT_RATE_PER_MIN` (default `20`, minimum `20`)
- `PI_BRIDGE_INTERRUPT_RATE_BURST` (default `4`, minimum `4`)

## Command

- `/pi-bridge-status`

## Development

```bash
npm test
npm pack --dry-run
```

Suggested release checklist:

1. Update version in `package.json`
2. Run tests (`npm test`)
3. Validate package tarball (`npm pack --dry-run`)
4. Tag and push release commit
5. Publish to npm (`npm publish --access public`)

## OSS best practices

- Keep package references scoped in docs/examples (`@jademind/pi-bridge`, `@jademind/pi-telemetry`).
- Keep bridge inbox/ack directories user-local (`~/.pi/agent/statusbridge`) and avoid world-writable permissions.
- Treat all inbox payloads as untrusted: validate PID, TTL, size, and path constraints before delivery.
- Keep rate limits enabled (normal + interrupt) to protect active sessions from spam and accidental loops.
- When changing envelope/ack schema, bump docs with explicit compatibility notes.
- Keep release notes aligned across npm package, Git tag, and dependent clients (status bar / mobile).

## License

MIT