AlertRun

See what your AI coding agents are doing — from your Mac's notch.

AlertRun is a lightweight macOS app that turns your MacBook's notch into a live status monitor for AI coding agents. It supports Kiro, Cursor, Windsurf, and Codex simultaneously.

---

How It Works

       ┌──────────────────────┐
       │     [  notch  ]      │
       │   ⠋ 2/3 Working     │  ← collapsed view
       └──────────────────────┘

       ┌──────────────────────┐
       │     [  notch  ]      │
       │ ⠋ ⚡ my-app    Build │  ← expanded (hover)
       │ ⠋ ▶︎ api       Refac │
       │ ● 🏄 frontend  Wait  │
       │ ✓ ◆ infra      Done  │
       └──────────────────────┘

The app fuses seamlessly with your Mac's notch — same width, same black background, extending downward to show agent status.

Features

• Multi-IDE support — Kiro, Cursor, Windsurf, Codex
• Multi-session — Monitor all your projects at once
• Notch-native — Auto-detects your screen's notch dimensions
• Zero config — Setup wizard handles everything
• Lightweight — No network, no telemetry, just file watching
• Launch at login — Always there when you need it

Supported IDEs

IDE	Integration Method	Precision
⚡ Kiro	.kiro/hooks/ (event-driven)	Exact
▶︎ Cursor	.cursor/rules/ (agent rules)	High
🏄 Windsurf	.windsurfrules (agent rules)	High
◆ Codex	AGENTS.md (agent rules)	High

Kiro uses native event hooks for precise status tracking. Cursor, Windsurf, and Codex use agent rules — instructions the AI follows to report its status.

Installation

Download

Download the latest .dmg from Releases.

Build from Source

# Clone
git clone https://github.com/alertrun/alertrun.git
cd alertrun

# Open in Xcode
open AlertRun.xcodeproj

# Or build from command line
xcodebuild -scheme AlertRun -configuration Release build

Setup

1. Launch AlertRun — it appears in your menubar
2. Follow the setup wizard — select IDEs, scan projects
3. Done — the notch overlay activates immediately

To add new projects later: Settings → Projects → Add Project

Requirements

• macOS 13.0+ (Ventura or later)
• MacBook with notch display (works without notch too, uses floating panel)

Architecture

~/.alertrun/
├── sessions/           ← status files (one per IDE+project)
│   ├── kiro-myapp.json
│   ├── cursor-api.json
│   └── ...
└── update-status.sh    ← embedded status writer

Project/.kiro/hooks/alertrun-status.json   ← Kiro hooks
Project/.cursor/rules/alertrun.mdc         ← Cursor rules
Project/.windsurfrules                     ← Windsurf rules (appended)
Project/AGENTS.md                          ← Codex rules (appended)

The app polls ~/.alertrun/sessions/*.json every second. Each IDE writes a JSON file with:

{
  "status": "in_progress",
  "title": "Building",
  "description": "Compiling modules...",
  "session": "my-project",
  "ide": "kiro",
  "timestamp": "2026-06-22T10:30:00Z"
}

Status Values

Status	Meaning	Display
idle	No active task	Gray dot
in_progress	Agent is working	Animated cyan spinner
waiting_on_user	Needs your input	Orange dot
completed	Task finished	Green checkmark

Building & Distribution

# Sign the app
./scripts/sign-and-notarize.sh

# Create DMG
./scripts/create-dmg.sh

See scripts/ for details on signing prerequisites.

Privacy

AlertRun:

• Makes zero network requests
• Collects no telemetry or analytics
• Only reads/writes files in ~/.alertrun/ and your project directories
• Runs entirely on your machine

License

MIT

---

AlertRun — Your AI agents, at a glance.