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.

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

More detail: Getting Started.

Two paths

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.

Project status

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.