Live observability for Pi

See every Pi session
at a glance.

Pi Beacon brings main sessions, subagents, context, tokens and daily cost into Waybar and Quickshell. Everything stays on your machine.

Install Pi Beacon

Open source. Local only. No telemetry.

Pi Beacon Overview showing one live Pi session, two associated subagents, model usage and seven-day daily cost — One view for sessions, subagents and usage.

Stay oriented

Know what Pi is doing without searching through terminal tabs.

Keep every session visible

See idle, running and waiting sessions from one compact desktop surface.

Catch agents that need you

Surface waiting prompts and child attention states before background work disappears.

Read Pi’s real numbers

Use live context, token and cost values directly from Pi’s in process state.

Bring your own interface

Consume the public snapshot contract or reshape the maintained Quickshell frontend.

Your agents should not disappear
inside terminal tabs.
Keep every Pi session in sight.

Three clear layers

A small driver, a public contract and a frontend you control.

Step 1

Pi publishes live state

The TypeScript extension writes atomic local snapshots from Pi lifecycle events.

Step 2

Python indexes history

Pydantic validates the contract while SQLModel resumes each JSONL file from its saved offset.

Step 3

Your desktop renders it

Waybar shows the signal. Quickshell opens the full view. Your own client can use the same JSON.

Built in the open

A typed local bridge with visible engineering boundaries.

91automated tests

87.48%Python coverage

0TCP listeners

v1documented contract

Pi extension  →  live bridge
Pi JSONL      →  async SQLite
local SSE     →  any frontend

Free and local

One command. Complete local installation.

Paste one command. The installer asks whether to install, update or uninstall, then offers the relevant desktop integration choices.

Open the interactive installer

curl -fsSL
              https://raw.githubusercontent.com/andres-ortizl/pi-beacon/v1.1.0/install.sh
              | sh

The same script installs and uninstalls Pi Beacon. It detects Quickshell, asks which configuration to use, preserves local data by default and requires explicit confirmation before purge. Later, pi-beacon update installs the newest release and refreshes every tracked integration. Automation flags remain available through --help.

Questions answered

What stays local, what gets indexed and what you can replace.

Does Pi Beacon upload session data?

No. It reads local Pi files and runtime state without uploading them. It has no telemetry, opens no TCP port and serves only a private Unix socket. Optional release checks request only public version metadata from GitHub.

Does it reread my complete history?

The historical cache watches changes and validates the saved byte offset. Set history_enabled to false for live-only operation.

Does it show the main Pi session?

Yes. The extension publishes each open session with its state, model, context and usage.

Does it support Pi subagents?

Yes. It reads the documented lifecycle artifacts created by pi subagents.

Can it notify me when Pi finishes?

Yes. Freedesktop notifications are enabled by default. The bundled completion sound is optional.

Do I need Quickshell?

No. The JSON snapshot and Waybar output work without Quickshell.

Can I replace the default design?

Yes. The driver knows nothing about the frontend. Use the snapshot API, provide another theme or copy and reshape the QML component.

Which platforms are supported?

Pi Beacon targets Linux desktops. The Python snapshot contract remains independent from Waybar and Quickshell.

How do I remove it?

Remove the Pi package, uninstall the uv tool and delete the optional local cache.

Ready when Pi is

Keep every Pi session in sight.