Cursor Agent Beacon
See what your Cursor agent is doing without watching the chat.
Top-bar status on Ubuntu/GNOME — and optionally a desk display with a pixel-robot status face.
Agents keep working while you alt-tab, walk away, or switch projects. Beacon turns native Cursor Hooks into glanceable states — so you know when it's thinking, running a shell, done, or stuck — without digging through the chat.
Who it's for: Cursor users on Ubuntu / GNOME (top-bar panel). Hooks + CLI work anywhere Cursor runs; the desk display is optional.
See it
Default theme — thinking → running shell → success. Bring your own GIFs anytime.
| Thinking | Running shell | Success | Error |
|---|---|---|---|
GNOME top-bar panel (multi-session: state, tool, turn timer):
| Thinking | Running shell |
|---|---|
Try the desk-display simulator: live preview · or open preview/display-simulator.html locally.
Quick start (desktop)
pip install cursor-agent-beacon
cursor-agent-beacon setup
Restart Cursor. On Ubuntu/GNOME, reload the shell if the top-bar panel does not appear (Alt+F2 → r on X11, or log out/in on Wayland).
cursor-agent-beacon doctor
cursor-agent-beacon status # after an Agent chat
You're done when doctor is green and the top bar shows agent state.
Install from git (development)
git clone https://github.com/suribe06/cursor-agent-beacon.git
cd cursor-agent-beacon
./setup.sh
More detail: Getting Started.
Two paths
| Path | What you get | Needs |
|---|---|---|
| Desktop (default) | GNOME top-bar panel + doctor / status CLI |
Ubuntu/GNOME + Cursor |
| Desk display (optional) | Same status on a physical 480×480 panel via a local bridge | ESP32 board + pip install "cursor-agent-beacon[bridge]" |
The desk display ships firmware and flash notes for the VIEWE 480×480 panel; other boards can speak the same serial protocol. See Hardware displays.
Features
- Glanceable agent states:
idle,waiting,thinking,running_shell,running_mcp,success,error - Multi-session GNOME panel (focused session + open workspaces)
- One-shot setup / uninstall; fail-open hooks (never block Cursor)
- Default pixel-robot theme + custom GIF themes (
themes/custom/) - Optional HTTP → serial bridge for a desk panel
Custom themes
Drop your own 480×480 GIFs under themes/custom/<name>/ — Pathfinder sprites, radars, whatever fits your desk. The robot is just the default face.
export CURSOR_AGENT_BEACON_THEME=your-theme
See Display themes and themes/README.md.
How it works
Cursor fires hook events during the agent lifecycle — the model does not self-report. Beacon maps those events to high-level states and publishes them through sinks (file, log, HTTP).
Cursor → ~/.cursor/hooks.json → cursor-agent-beacon run → mapper → sinks
↓
~/.local/share/cursor-agent-beacon/ → GNOME panel
Details: docs/architecture.md.
Environment variables
| Variable | Default | Description |
|---|---|---|
CURSOR_AGENT_BEACON_LOG |
true |
Emit JSON lines to stderr |
CURSOR_AGENT_BEACON_FILE |
true |
Write latest status file |
CURSOR_AGENT_BEACON_STATUS_FILE |
~/.local/share/cursor-agent-beacon/status.json |
Status snapshot path |
CURSOR_AGENT_BEACON_HTTP_URL |
unset | Bridge POST /status endpoint |
CURSOR_AGENT_BEACON_BRIDGE_HOST |
127.0.0.1 |
Bridge bind address |
CURSOR_AGENT_BEACON_BRIDGE_PORT |
8765 |
Bridge HTTP port |
CURSOR_AGENT_BEACON_SERIAL_PORT |
unset | ESP32 serial device (dry-run if unset) |
CURSOR_AGENT_BEACON_SERIAL_BAUD |
115200 |
Serial baud rate |
CURSOR_AGENT_BEACON_THEME |
standard |
Theme id (standard or custom name) |
CURSOR_AGENT_BEACON_THEMES_DIR |
packaged / repo themes/ |
Theme packs root |
CURSOR_AGENT_BEACON_REDACT_CONTENT |
false |
Hide prompt/response text in status |
Project status
| Component | Status |
|---|---|
| Python hook handler | ✅ shipped |
| Setup + doctor / status CLI | ✅ shipped |
| Multi-session file sink | ✅ shipped |
| GNOME status panel | ✅ usable (polishing) |
| Standard GIF theme | ✅ bundled |
| Custom GIF themes | ✅ themes/custom/ |
| Local bridge service | ✅ shipped |
| VIEWE desk-display firmware | ✅ in-repo (firmware/viewe/) |
See docs/roadmap.md.
Documentation
- Getting Started
- GNOME Status Panel
- Display themes
- Hooks Reference
- Architecture
- Hardware displays
- Hardware — VIEWE setup
- Roadmap
- Changelog
Contributing
See CONTRIBUTING.md. Please read the Code of Conduct before participating.
Report security issues privately — see SECURITY.md.
Development
./setup.sh
source .venv/bin/activate
pip install -e ".[dev,bridge]"
pytest -m "not smoke"
ruff check src tests
ruff format --check src tests
pyright
Bridge systemd unit: packaging/cursor-agent-beacon-bridge.service · install script: ./scripts/install-bridge-service.sh
License
MIT — see LICENSE.
Metadata
Release files for cursor-agent-beacon 0.5.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cursor_agent_beacon-0.5.4.tar.gz | 108.2 kB | Without provenance | Details for cursor_agent_beacon-0.5.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cursor_agent_beacon-0.5.4-py3-none-any.whl | Python 3 | none | any | Details for cursor_agent_beacon-0.5.4-py3-none-any.whl |
Total release size: 242.2 kB
Release files / cursor_agent_beacon-0.5.4.tar.gz
| Download URL | cursor_agent_beacon-0.5.4.tar.gz |
|---|---|
| Size | 108.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d3967335f5a25826611abf1d7e62fe0af17ebc1634ab851c5fa066ecb3217f6a
|
|
BLAKE2b-256 checksum How to use checksums |
abad74dde987cf60b60e142bba44509f29186717e504ce5806ec445ac8d83404
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / cursor_agent_beacon-0.5.4-py3-none-any.whl
| Download URL | cursor_agent_beacon-0.5.4-py3-none-any.whl |
|---|---|
| Size | 134.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d2d2d0b5f428ea40d1c6d9d9d6d96c153c5241898111f839bc452906fe71670d
|
|
BLAKE2b-256 checksum How to use checksums |
203b9471610bcddf193cf41c2f23c25b350826161c3b7e9a846e12acacd9c06e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for cursor-agent-beacon 0.5.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.