cursor-agent-beacon 0.3.1

Deterministic Cursor agent status monitoring via native hooks

Cursor Agent Beacon

Deterministic monitoring of Cursor agent activity using native Cursor Hooks.

Repository: https://github.com/suribe06/cursor-agent-beacon

Cursor fires hook events automatically during the agent lifecycle. Cursor Agent Beacon listens to those events, maps them to a small set of high-level states, and publishes status updates through pluggable sinks.

This is the software foundation for a physical status panel (ESP32 + color TFT). v0.3 ships Python hooks, bundled standard GIF themes, a local bridge service, and one-shot setup.

Features

• One-shot setup: ./setup.sh or pip install + cursor-agent-beacon setup
• doctor / status / uninstall CLI for install verification and teardown
• Normalized status model (idle, thinking, running_shell, running_mcp, success, error, ...)
• Standard theme: 8 animated pixel-robot GIFs (480×480) in themes/standard/assets/
• Custom themes: drop your own GIFs in themes/custom/<name>/
• Fail-open behavior — hooks never block Cursor
• JSON log sink (stderr) for the Hooks output channel
• File sink with latest status snapshot
• HTTP sink for the local bridge service
• Bridge service (cursor-agent-beacon bridge): POST /status → theme GIF resolution → serial commands
• GNOME status panel (v0.10, pre-release): Ubuntu top-bar indicator — gnome-extension/ + docs/gnome-panel.md
• Multi-session registry: per-chat status under ~/.local/share/cursor-agent-beacon/

Quick start

From git (recommended for 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.

Verify installation:

.venv/bin/cursor-agent-beacon doctor

After using the agent:

.venv/bin/cursor-agent-beacon status

Check status (any project):

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

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

Architecture

Cursor → hooks.json → hook-handler.py → cursor_agent_beacon → sinks

Read more in docs/architecture.md.

Configuration

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	.cursor-agent-beacon/status.json (project) or ~/.local/share/cursor-agent-beacon/status.json (user install)	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 theme name)
CURSOR_AGENT_BEACON_THEMES_DIR	packaged themes/ or repo themes/	Root folder for theme packs
CURSOR_AGENT_BEACON_REDACT_CONTENT	false	Hide prompt/response text in status

Project status

Component	Status
Python hook handler	✅ v0.3
Multi-session file sink	✅ v0.3
One-shot setup + doctor CLI	✅ v0.3
GNOME status panel	🧪 v0.10 pre-release
Standard GIF theme	✅ bundled
Custom GIF themes	✅ themes/custom/
Local bridge service	✅ v0.2
VIEWE display firmware	🔜 planned

See docs/roadmap.md.

Documentation

• Getting Started
• Hooks Reference
• GNOME Status Panel
• Architecture
• Hardware — VIEWE
• 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
ruff check src tests
ruff format --check src tests
pyright
python -m build
cursor-agent-beacon bridge
cursor-agent-beacon install-hooks
PYTHONPATH=src python3 -m cursor_agent_beacon.cli map examples/sample-events/stop_completed.json

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

License

MIT — see LICENSE.