Files

docs: add README with installation and usage instructions

Made-with: Cursor

2026-03-10 02:57:31 -04:00

2.8 KiB

Raw Blame History

cursor-flasher

A macOS daemon that flashes a pulsing border around Cursor IDE windows when the AI agent is waiting for your input. Optionally plays a system sound.

Prerequisites

macOS
Python 3.10+
Accessibility permission granted to your terminal (System Settings → Privacy & Security → Accessibility)

Installation

git clone <repo-url> && cd cursor-flasher
pip install -e ".[dev]"

Usage

# Start the daemon (backgrounds automatically)
cursor-flasher start

# Start in foreground (useful for debugging)
cursor-flasher start --foreground

# Check if the daemon is running
cursor-flasher status

# Stop the daemon
cursor-flasher stop

How It Works

Polls Cursor's macOS accessibility tree every 500ms
Detects agent state by looking for specific UI elements (Stop/Accept/Reject buttons)
When the agent finishes and is waiting for input, shows a pulsing amber border around only the window(s) that need attention
Plays a system sound (default: "Glass")
Dismisses automatically when the agent starts working again, or after a timeout

Configuration

Create ~/.cursor-flasher/config.yaml to customize:

pulse:
  color: "#FF9500"    # Border color (hex)
  width: 4            # Border thickness (px)
  speed: 1.5          # Pulse cycle duration (seconds)
  opacity_min: 0.3    # Minimum pulse opacity
  opacity_max: 1.0    # Maximum pulse opacity

sound:
  enabled: true       # Play sound on trigger
  name: "Glass"       # macOS system sound name
  volume: 0.5         # Volume (0.0 - 1.0)

detection:
  poll_interval: 0.5  # Seconds between accessibility tree polls
  cooldown: 3.0       # Seconds before re-triggering after dismissal

timeout:
  auto_dismiss: 300   # Auto-hide overlay after N seconds

All values are optional — defaults are used for anything not specified.

Troubleshooting

"Cursor is not running" / no detection: Make sure Cursor is open. The daemon looks for the process by bundle ID.

No overlay appears: Grant Accessibility permission to your terminal app: System Settings → Privacy & Security → Accessibility. You may need to restart the terminal after granting.

Overlay appears on wrong windows: Detection is per-window — only windows with active approval prompts (Accept, Reject, Run, etc.) should flash. If you see false positives, the detection patterns may need tuning for your Cursor version. Check scripts/dump_a11y_tree.py to inspect the accessibility tree.

Development

# Run tests
pytest tests/ -v

# Dump Cursor's accessibility tree (for debugging detection)
python scripts/dump_a11y_tree.py --depth 8

# Manual overlay test (flashes all windows for 10 seconds)
python scripts/test_overlay.py

# Manual overlay test (only windows needing attention)
python scripts/test_overlay.py --per-window

2.8 KiB Raw Blame History