Cursor Agent Beacon

Deterministic monitoring of Cursor agent activity using native Cursor Hooks.

Cursor fires hook events automatically during the agent lifecycle — the model does not need to report status. Cursor Agent Beacon maps those events to a small set of high-level states and publishes updates through pluggable sinks (file, log, HTTP).

Use it today for a GNOME top-bar status panel and CLI (doctor / status). Optionally drive a physical VIEWE 480×480 panel (ESP32 firmware + local bridge); other displays can speak the same serial protocol.

GNOME status panel

Thinking	Running shell

On Ubuntu/GNOME, the extension reads ~/.local/share/cursor-agent-beacon/ and shows the focused agent session in the top bar (state, tool name, turn timer). The menu lists open workspace sessions. See GNOME Status Panel.

Quick start

From git (development)

git clone https://github.com/suribe06/cursor-agent-beacon.git
cd cursor-agent-beacon
./setup.sh

From PyPI

python3 -m venv .venv
source .venv/bin/activate
pip install "cursor-agent-beacon[bridge]"
cursor-agent-beacon setup

Restart Cursor when setup finishes. On Ubuntu, reload GNOME Shell if the top-bar panel does not appear (Alt+F2 → r on X11, or log out/in on Wayland).

Verify and inspect:

cursor-agent-beacon doctor
cursor-agent-beacon status    # after an Agent chat

Raw status file (any project):

cat ~/.local/share/cursor-agent-beacon/status.json

See Getting Started for bridge, themes, and development setup.

Features

Desktop (shipped)

• One-shot setup: ./setup.sh or pip install + cursor-agent-beacon setup
• doctor / status / uninstall CLI
• GNOME status panel (v0.10 pre-release) with multi-session registry
• Normalized states: idle, waiting, thinking, running_shell, running_mcp, success, error
• Fail-open hooks — never block Cursor

Themes & hardware (optional)

• Standard pixel-robot GIF theme (480×480) in themes/standard/assets/
• Custom themes in themes/custom/<name>/
• Local bridge (cursor-agent-beacon bridge): HTTP → serial (ESP32)
• VIEWE UEDX48480021-MD80ET firmware + flash script (setup)
• Bring-up notes for other displays (hardware hub)

Architecture

Cursor → ~/.cursor/hooks.json → cursor-agent-beacon run → mapper → sinks
                                                      ↓
                              ~/.local/share/cursor-agent-beacon/ → GNOME panel

Read more in docs/architecture.md.

Configuration

Project status

See docs/roadmap.md.

Documentation

• Getting Started
• Hooks Reference
• GNOME Status Panel
• Architecture
• Hardware displays (hub + other boards)
• 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
python -m build

Systemd user service template: packaging/cursor-agent-beacon-bridge.service

# Install + enable bridge in the background (uses config/hardware.env)
./scripts/install-bridge-service.sh
# logs: journalctl --user -u cursor-agent-beacon-bridge -f

License

MIT — see LICENSE.