cursor-flasher/README.md

> [!NOTE]  
> This project was developed entirely with AI coding assistance (Claude Opus 4.6 via Cursor IDE) and has not undergone manual review. It is provided as-is and may require adjustments for other environments.

# cursor-flasher

A macOS daemon that flashes a pulsing border and plays a sound when your [Cursor](https://cursor.com) AI agent needs attention.

## How It Works

Uses [Cursor hooks](https://cursor.com/docs/agent/hooks) for reliable detection:

- `**preToolUse**` — fires when the agent wants to run a shell command, write a file, or use any tool that may need approval. **Pulses** the border continuously and plays a sound until you click the Cursor window.
- `**stop`** — fires when the agent loop ends. **Flashes** the border once, briefly.

Only tools in the `approval_tools` list trigger the pulse (default: `Shell`, `Write`, `Delete`). Auto-approved tools like `Read` and `Grep` are ignored.

## Prerequisites

- macOS
- [uv](https://docs.astral.sh/uv/)
- Cursor IDE
- **Accessibility** permission for your terminal (System Settings → Privacy & Security → Accessibility) — needed for window enumeration
- **Input Monitoring** permission for the daemon process (System Settings → Privacy & Security → Input Monitoring) — needed for input-based pulse dismissal

## Installation

```bash
# Clone and install
git clone https://code.cottongin.xyz/cursor-flasher && cd cursor-flasher
uv sync

# Install Cursor hooks (global, applies to all projects)
uv run cursor-flasher install

# Start the daemon
uv run cursor-flasher start
```

The `install` command copies the hook script to `~/.cursor/hooks/` and adds entries to `~/.cursor/hooks.json`. Cursor auto-reloads hooks.

## Usage

```bash
uv run cursor-flasher start              # background daemon
uv run cursor-flasher start --foreground  # foreground (for debugging)
uv run cursor-flasher status
uv run cursor-flasher stop
```

## Configuration

Optional config file at `~/.cursor-flasher/config.yaml`:

```yaml
theme: "auto"               # "dark", "light", or "auto" (follows macOS appearance)

dark:                        # styles used when OS is in dark mode
  running:                   # approval pulse (continuous until you interact)
    color: "#FF9500"         # border color (hex)
    width: 4                 # border thickness in pixels
    opacity: 0.85            # max border opacity
    pulse_speed: 1.5         # pulse cycle speed in seconds
    sound: "Glass"           # macOS system sound ("" to disable)
    volume: 0.5              # 0.0 to 1.0
    # sounds: Basso, Blow, Bottle, Frog, Funk, Glass, Hero,
    #         Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink
  completed:                 # agent stop flash (brief fade-in/out)
    color: "#00FF00"         # different color for completion
    width: 4
    opacity: 0.85
    duration: 1.5            # flash duration in seconds
    sound: ""                # no sound by default (Cursor plays its own)
    volume: 0.0

light:                       # styles used when OS is in light mode
  running:
    color: "#3B82F6"
    width: 4
    opacity: 0.9
    pulse_speed: 1.5
    sound: "Glass"
    volume: 0.5
  completed:
    color: "#22C55E"
    width: 4
    opacity: 0.9
    duration: 1.5
    sound: ""
    volume: 0.0

flash:
  mode: "screen"             # "window", "screen", or "allscreens"

# Tools that trigger the pulse + sound (approval mode).
# Others are silently ignored (e.g., Read, Grep, Glob, Task).
approval_tools:
  - Shell
  - Write
  - Delete

general:
  approval_delay: 2.5        # seconds to wait before pulsing (filters auto-approvals)
  cooldown: 2.0              # minimum seconds between flashes
```

Styles are organized under `dark` and `light` theme sections, each containing `running` (approval pulse) and `completed` (stop flash) modes with their own color, border, and sound settings. The `theme` option controls which styles are active: set `"auto"` to follow macOS appearance in real-time, or force `"dark"` / `"light"`. Set `sound: ""` to disable sound for a particular mode.

## Uninstall

```bash
uv run cursor-flasher uninstall
uv run cursor-flasher stop
```

## Troubleshooting

**Flashing on every tool call (too noisy):**

- Edit `~/.cursor-flasher/config.yaml` and narrow down `approval_tools` to just `Shell`.

**No flash at all:**

- Check daemon: `uv run cursor-flasher status`
- Check hooks installed: `ls ~/.cursor/hooks/cursor-flasher-notify.py`
- Check Cursor Settings → Hooks tab for execution logs

**Pulse doesn't stop:**

- Click the Cursor window to bring it to focus — the pulse auto-dismisses when Cursor is the frontmost app.