cursor-agent-beacon 0.3.1__tar.gz

cursor_agent_beacon-0.3.1/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.venv/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Local status / runtime
+.cursor-agent-beacon/
+themes/custom/*
+!themes/custom/README.md
+!themes/custom/example/
+!themes/custom/example/**
+firmware/viewe/data/**/*.png
+config/hardware.env
+*.log
+
+# OS
+.DS_Store
+Thumbs.db

cursor_agent_beacon-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cursor-agent-beacon contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cursor_agent_beacon-0.3.1/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: cursor-agent-beacon
+Version: 0.3.1
+Summary: Deterministic Cursor agent status monitoring via native hooks
+Project-URL: Homepage, https://github.com/suribe06/cursor-agent-beacon
+Project-URL: Documentation, https://github.com/suribe06/cursor-agent-beacon#readme
+Project-URL: Issues, https://github.com/suribe06/cursor-agent-beacon/issues
+Project-URL: Repository, https://github.com/suribe06/cursor-agent-beacon
+Author: cursor-agent-beacon contributors
+License-File: LICENSE
+Keywords: agent,cursor,hooks,monitoring,observability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Provides-Extra: bridge
+Requires-Dist: pyserial>=3.5; extra == 'bridge'
+Provides-Extra: dev
+Requires-Dist: pillow>=10.0; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Provides-Extra: export
+Requires-Dist: pillow>=10.0; extra == 'export'
+Description-Content-Type: text/markdown
+
+# Cursor Agent Beacon
+
+[![CI](https://github.com/suribe06/cursor-agent-beacon/actions/workflows/ci.yml/badge.svg)](https://github.com/suribe06/cursor-agent-beacon/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+Deterministic monitoring of Cursor agent activity using native [Cursor Hooks](https://cursor.com/docs/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/`](gnome-extension/) + [`docs/gnome-panel.md`](docs/gnome-panel.md)
+- **Multi-session registry**: per-chat status under `~/.local/share/cursor-agent-beacon/`
+
+## Quick start
+
+### From git (recommended for development)
+
+```bash
+git clone https://github.com/suribe06/cursor-agent-beacon.git
+cd cursor-agent-beacon
+./setup.sh
+```
+
+### From PyPI
+
+```bash
+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:
+
+```bash
+.venv/bin/cursor-agent-beacon doctor
+```
+
+After using the agent:
+
+```bash
+.venv/bin/cursor-agent-beacon status
+```
+
+Check status (any project):
+
+```bash
+cat ~/.local/share/cursor-agent-beacon/status.json
+```
+
+See [Getting Started](docs/getting-started.md) for bridge, themes, and development setup.
+
+## Architecture
+
+```text
+Cursor → hooks.json → hook-handler.py → cursor_agent_beacon → sinks
+```
+
+Read more in [`docs/architecture.md`](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`](docs/roadmap.md).
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md)
+- [Hooks Reference](docs/hooks.md)
+- [GNOME Status Panel](docs/gnome-panel.md)
+- [Architecture](docs/architecture.md)
+- [Hardware — VIEWE](docs/hardware-viewe.md)
+- [Roadmap](docs/roadmap.md)
+- [Changelog](CHANGELOG.md)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Please read the [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
+
+Report security issues privately — see [SECURITY.md](SECURITY.md).
+
+## Development
+
+```bash
+./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`](packaging/cursor-agent-beacon-bridge.service)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cursor_agent_beacon-0.3.1/README.md

@@ -0,0 +1,146 @@
+# Cursor Agent Beacon
+
+[![CI](https://github.com/suribe06/cursor-agent-beacon/actions/workflows/ci.yml/badge.svg)](https://github.com/suribe06/cursor-agent-beacon/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+Deterministic monitoring of Cursor agent activity using native [Cursor Hooks](https://cursor.com/docs/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/`](gnome-extension/) + [`docs/gnome-panel.md`](docs/gnome-panel.md)
+- **Multi-session registry**: per-chat status under `~/.local/share/cursor-agent-beacon/`
+
+## Quick start
+
+### From git (recommended for development)
+
+```bash
+git clone https://github.com/suribe06/cursor-agent-beacon.git
+cd cursor-agent-beacon
+./setup.sh
+```
+
+### From PyPI
+
+```bash
+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:
+
+```bash
+.venv/bin/cursor-agent-beacon doctor
+```
+
+After using the agent:
+
+```bash
+.venv/bin/cursor-agent-beacon status
+```
+
+Check status (any project):
+
+```bash
+cat ~/.local/share/cursor-agent-beacon/status.json
+```
+
+See [Getting Started](docs/getting-started.md) for bridge, themes, and development setup.
+
+## Architecture
+
+```text
+Cursor → hooks.json → hook-handler.py → cursor_agent_beacon → sinks
+```
+
+Read more in [`docs/architecture.md`](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`](docs/roadmap.md).
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md)
+- [Hooks Reference](docs/hooks.md)
+- [GNOME Status Panel](docs/gnome-panel.md)
+- [Architecture](docs/architecture.md)
+- [Hardware — VIEWE](docs/hardware-viewe.md)
+- [Roadmap](docs/roadmap.md)
+- [Changelog](CHANGELOG.md)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Please read the [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
+
+Report security issues privately — see [SECURITY.md](SECURITY.md).
+
+## Development
+
+```bash
+./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`](packaging/cursor-agent-beacon-bridge.service)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cursor_agent_beacon-0.3.1/firmware/viewe/README.md

@@ -0,0 +1,90 @@
+# VIEWE UEDX48480021-MD80E firmware
+
+Firmware for the **VIEWE ESP32-S3 Knob Display** (480×480 circular, ST7701S, LVGL).
+
+## Before you have the board
+
+You can still prepare and test:
+
+| Step | Command | What it validates |
+| --- | --- | --- |
+| Bridge → serial | `scripts/fake_serial_device.py` | Protocol lines without hardware |
+| Export frames | `scripts/export_firmware_assets.py` | PNG sequences for LVGL |
+| Protocol parser | `protocol.cpp` + unit test on PC (optional) | `STATUS\|...\` parsing |
+
+## When the board arrives
+
+### 1. Arduino IDE setup
+
+1. Install [Arduino ESP32 core](https://docs.espressif.com/projects/arduino-esp32/en/latest/) (ESP32-S3).
+2. Library Manager:
+   - `ESP32_Display_Panel` (≥ 1.0.3)
+   - `lvgl` (8.4.x per VIEWE docs)
+3. Clone vendor examples: [VIEWESMART/ESP32-Arduino](https://github.com/VIEWESMART/ESP32-Arduino) → `examples/2.1inch`.
+4. Board: **ESP32-S3**. Select the macro for `UEDX48480021-MD80E` in `ESP32_Display_Panel` config.
+5. Confirm the **USB serial baud rate** in the vendor example (often `115200` on ESP32-S3 USB-CDC). Match `CURSOR_AGENT_BEACON_SERIAL_BAUD`.
+
+### 2. Flash workflow
+
+1. Open `examples/2.1inch` from VIEWESMART — verify the panel + knob work **before** merging beacon code.
+2. Copy initialization from the vendor example into `cursor_agent_beacon/cursor_agent_beacon.ino`.
+3. Wire in `protocol.cpp` for serial `STATUS|state|message` lines.
+4. Load PNG frames from `data/standard/` (SPIFFS/LittleFS) using `manifest.json`.
+5. Map `state` → sprite folder → LVGL `lv_img` animation.
+
+### 3. Connect to the bridge
+
+```bash
+# Find port (Linux)
+ls /dev/ttyACM* /dev/ttyUSB*
+
+export CURSOR_AGENT_BEACON_SERIAL_PORT=/dev/ttyACM0
+export CURSOR_AGENT_BEACON_SERIAL_BAUD=115200
+cursor-agent-beacon bridge
+```
+
+Send a test status:
+
+```bash
+export CURSOR_AGENT_BEACON_HTTP_URL=http://127.0.0.1:8765/status
+python3 scripts/simulate_hook.py examples/sample-events/after_agent_thought.json
+```
+
+## Serial protocol
+
+See [`docs/hardware-viewe.md`](../../docs/hardware-viewe.md) and Python mirror in `src/cursor_agent_beacon/protocol.py`.
+
+```text
+PC → device:  STATUS|<state>|<message>
+PC → device:  THEME|<theme_id>
+device → PC:  EVENT|button_pressed   (optional, future MCP path)
+```
+
+## Asset layout
+
+```text
+data/standard/
+  manifest.json       # state → sprite → frame list
+  thinking/
+    frame_00.png
+    frame_01.png
+    ...
+```
+
+Regenerate after theme changes:
+
+```bash
+python3 scripts/export_standard_gifs.py
+python3 scripts/export_firmware_assets.py
+```
+
+## Files in this folder
+
+| File | Purpose |
+| --- | --- |
+| `protocol.h` / `protocol.cpp` | Parse `STATUS\|...\` lines (portable C++) |
+| `cursor_agent_beacon/cursor_agent_beacon.ino` | Sketch skeleton — merge with VIEWESMART init |
+
+## Display-only scope
+
+This repo focuses on **showing agent status**. Knob/button `EVENT|...` lines are defined in the protocol for future use but are not required for the first end-to-end test.