MeetAlert

Unmissable meeting alerts for your Mac.

Desktop popup + phone push + urgent escalation — so "I didn't see the calendar reminder" stops being an excuse.

brew install --cask roypadina/tap/meetalert

---

Table of Contents

• Features
• Install
• Requirements
• Screenshots
• ntfy setup
  • Why not ntfy's insistent ring?
• How it works
• Configuration
• Filtering / ignoring events
• Joining a meeting
• Morning agenda
• Testing
• Google Calendar (and any other calendar)
• Support
• License

Features

• Multiple alerts per meeting at whatever offsets you configure — minutes before, at start, or after (a late nag) — not just one.
• Desktop popup that stays on screen until you act on it — no auto-dismiss, no silently missed alert — shown on whichever display your mouse is on.
• Live countdown that changes colour as it gets close — a large ticking numeral (minutes, then seconds, then how late you are) with the whole card shifting cyan → amber → red, and a pulsing rim once escalation has pinged your phone. State is always spelled out in words and icons too, never colour alone.
• A colour per calendar — each alert shows its calendar's name and colour dot, starting from the colour macOS already uses in Calendar.app and overridable per calendar in Settings → Calendars.
• Keyboard shortcuts on the popup — click the card once (this never steals focus from the app you're typing in), then ↩/J join · 5 snooze 5m · 1 snooze 1m · T until start · esc snooze. The two final actions need a modifier on purpose, so ordinary typing can never kill an alert: ⌘D dismiss, ⌘⇧I ignore.
• One-tap Join — a prominent Join button (and a matching push action) opens the Zoom/Meet/Teams/Webex/Whereby link straight from the alert, and every upcoming meeting with a link is joinable from the menu bar too.
• Phone push via ntfy at the same moment, with tappable ACK, Join, and Snooze 5m actions.
• Away-aware escalation — idle past a threshold or screen-locked, and the first push already goes out at urgent priority instead of waiting on a grace window nobody at the desk would see.
• Repeating urgent escalation — up to escalationRepeats re-pushes (3 by default, never past 15 minutes after the meeting starts) until you ack or snooze, not just one.
• Morning agenda push — an optional daily rundown of today's meetings and your largest free gap.
• Reads every calendar macOS syncs — Google, iCloud, Exchange, CalDAV — with zero API setup, and skips meetings you've declined. See below.
• Travel-lead alerts for meetings with a physical address — one extra early alert to account for getting there.

Install

Homebrew

brew install --cask roypadina/tap/meetalert

Requirements

macOS 14 Sonoma or later · Apple Silicon and Intel (universal binary)

First launch

MeetAlert is ad-hoc signed (not notarized). If macOS blocks it, open System Settings → Privacy & Security, scroll down and click Open Anyway next to MeetAlert (right-click → Open no longer works on macOS 15+). Or clear quarantine once:

xattr -dr com.apple.quarantine /Applications/MeetAlert.app

On first launch macOS will prompt for Calendar access — MeetAlert can't see your meetings without it. A Welcome window then offers to open MeetAlert at login (you can change it any time in Settings → Alerts, or in System Settings → General → Login Items & Extensions); MeetAlert never adds itself silently. Reopen the Welcome window any time from Welcome Guide… in the status menu. See the Installation wiki page.

Build from source

git clone https://github.com/roypadina/MeetAlert.git
cd MeetAlert
./build.sh
open build/MeetAlert.app

build.sh runs swift build -c release --arch arm64 --arch x86_64 (universal) and assembles/ad-hoc-signs build/MeetAlert.app. No Xcode project — it's a plain Swift Package executable.

ntfy setup

This is the part that makes escalation actually reach your phone — don't skip it.

1. Install the ntfy app: App Store (iOS) or Play Store (Android).
2. Pick a private, random topic name — a long random string, e.g. meetalert-9f3a1c7b2e. A topic name is effectively a password: on the public ntfy.sh server, anyone who knows the name can publish to it or read it. Don't use anything guessable.
3. In the ntfy app, subscribe to that topic (and leave the server as ntfy.sh, unless you're self-hosting).
4. Put the same topic (and server, if not ntfy.sh) into MeetAlert: menu bar icon → Settings… → ntfy section, or edit ~/.config/meetalert/config.json directly.

   ntfyTopic is empty by default — phone push, and escalation with it, stays completely off until you set one. This step is required for anything beyond the desktop popup.

5. In the ntfy app, make sure urgent (priority 5) notifications are set up to bypass silence/Do Not Disturb — that's the whole point of the escalation. The exact steps differ between Android and iOS and are more fiddly than you'd hope; see the ntfy Setup wiki page for the per-platform walkthrough (short version: Android needs a per-channel "override Do Not Disturb" toggle; iOS's Focus-mode bypass is a known ntfy limitation, so also allow the ntfy app explicitly under Focus mode settings as a backstop).
6. On Android, leave Settings → Notifications → "Keep alerting for highest priority" off (that's the default) and let MeetAlert do the repeating instead — see Why not ntfy's insistent ring? below. If you turn it on anyway, tapping ACK will not silence it.

Self-hosted ntfy servers work the same way — just set ntfyServer to your own instance. If it requires a login, paste an ntfy access token in Settings → ntfy (stored in the macOS Keychain, sent only to that server, including inside the ACK / Snooze buttons); an optional fallback topic URL gets the alert (without buttons) if the main server is unreachable. Details in the ntfy Setup wiki page. Keep message caching enabled on the server (the default) — with cache-duration: 0, there's no message history left to poll, so MeetAlert can never see an ACK/snooze reply and escalates the full escalationRepeats times regardless of whether you actually acked.

Why not ntfy's insistent ring?

The ntfy Android app has a "Keep alerting for highest priority" setting (off by default) that loops an alarm sound for every priority-5 notification until it's stopped. It sounds like exactly what MeetAlert wants. It isn't — tapping ACK cannot stop it.

In the app, that loop is one shared MediaPlayer, and only two things ever stop it:

• swiping the notification away (its delete intent), or
• opening the topic's detail screen in the app.

An action button with clear: true — which is what MeetAlert's ACK and Snooze 5m are — cancels the notification programmatically. A programmatic cancel does not fire the delete intent, so the loop keeps playing over a notification that is already gone and already marked read. Same for a view action with clear: true. There is no publish-side way to stop it either: nothing you can send to the topic silences a ring that's already started.

The result, if you enable it: ACK reaches MeetAlert and stops the escalation correctly, and the phone keeps ringing anyway until you separately swipe the (vanished) notification or open the topic. Swiping first doesn't help — ntfy has no dismiss callback, so a swipe tells MeetAlert nothing, isn't an ack, and the next escalation re-push starts the ring again.

So leave that setting off and let MeetAlert own the repetition: set a short escalationSeconds and a higher escalationRepeats (e.g. 45 and 8 ≈ six minutes of pings). Every ping is a normal priority-5 notification you can silence, and a single ACK genuinely ends all of them.

The popup

One instrument, read from across the room: a big monospaced-digit countdown, and a colour that changes with urgency rather than decoration.

State	When	Colour	Countdown
Starting in	more than 60 s to go	cyan	minutes (3 / min)
Starting in	60 s or less	amber	seconds (35 / sec)
Started	at or after the start	coral	now, then +2 / min late
Not acknowledged — phone alerted	escalation has pushed to your phone	keeps the state colour	unchanged, rim thickens and pulses

Urgency is never colour alone — the state word, the icon, the rim width and the countdown's unit all change together, so it survives colour-blindness, Increase Contrast (which drops the translucency for an opaque background and a heavier border) and Reduce Motion (which keeps the fades and drops the movement).

The row of actions is Join (the one filled button, ↩), Snooze 5m, Dismiss (⌘D), Ignore/Ignore series (⌘⇧I), and More ▾ holding the two remaining snoozes. With no meeting link, Dismiss becomes the filled button — there's always exactly one. Nothing about the layout changes on hover; only the buttons themselves light up.

How it works

When	What happens
Each offset in alertMinutesBefore (before, at, or after start), plus one travelLeadMinutes offset for meetings with a physical address	Desktop popup appears on whichever screen your mouse is on, and an ntfy push goes out with ACK, Join (if there's a meeting link), and Snooze 5m actions. Tapping the push body itself opens the meeting link.
You're away from the Mac (idle past awayIdleSeconds, or the screen is locked)	That first push skips the high-priority grace window and goes straight out at urgent priority — nobody's at the desk to see the popup anyway.
Several offsets of the same meeting come due in one scan (e.g. the event synced in late)	They collapse into one alert — the latest due one — instead of stacking popups.
Anything up to escalation	Clicking Dismiss, Join, Snooze, Till start, or Ignore forever on the popup — or tapping ACK on the push — counts as acknowledged; escalation stops. Tapping Snooze 5m on the push snoozes it (clamped to the meeting's start) and also stops escalation. Tapping ACK or Snooze 5m on the push also clears that notification from the phone and marks it read — but it does not stop ntfy's insistent ring if you enabled that; see Why not ntfy's insistent ring?. Tapping Join on the push only opens the meeting — it does not ack (that action never reports back to MeetAlert); the desktop popup's Join button does both.
Dismiss/ACK/Join on any of a meeting's alerts	That whole meeting occurrence is done: every remaining offset (including a not-yet-fired travel-lead or at-start alert) is suppressed, and any pending snooze for it is dropped. Snoozing, by contrast, only quiets that one alert until the snooze comes due.
escalationSeconds after an unacked alert, repeating	The push resends at urgent priority (rotating_light tag, titled and numbered ) and the desktop popup switches to a pulsing state — up to times ( by default), and never past after the meeting's start. If an alert itself first fires later than that (e.g. a very late offset), there's no escalation window left at all — just the one initial push.

Each offset of a meeting occurrence alerts once (tracked in state.json); a snooze that comes back due re-shows the popup without re-sending a push or re-arming escalation. MeetAlert also rescans immediately on system wake, not just every 30 seconds.

Configuration

Everything lives in ~/.config/meetalert/config.json, written with defaults on first launch, and re-read every 30 seconds — so a hand edit (or a Settings-window change) applies without restarting the app. Menu bar icon → Settings… gives you a native GUI for all of this except raw file editing.

Field	Default	Meaning
alertMinutesBefore	[3, 0]	Minutes before start to fire an alert — one entry per alert. 0 = at start, negative = that many minutes after start (a late alert). Deduplicated and sorted (descending) on load.
lateAlertMinutes	10	Still fire a missed alert up to this many minutes after its scheduled time (sync-lag cushion).
escalationSeconds	120	Seconds between each escalation re-push (never past 15 minutes after the meeting's start).
escalationRepeats	3	How many urgent re-pushes before MeetAlert gives up. Raise it (with a shorter escalationSeconds) to replace ntfy's insistent ring with repetition MeetAlert controls — an ACK stops these, insistent can't be stopped.
awayIdleSeconds	120	Idle time (or an immediate screen lock) before MeetAlert treats you as away and sends the first push at urgent priority instead of high.
travelLeadMinutes	30	Extra early alert for meetings with a physical (non-video-call) location.
agendaTime	null	Minutes since midnight (local time) to push today's agenda — e.g. 619 = 10:19; use the Settings time picker instead of computing this by hand. null = off. A legacy agendaHour value migrates automatically.
ignoreAllDay	true	Skip all-day events entirely.
ignoreKeywords	[]	Case-insensitive substrings — any event title containing one is skipped.
ntfyServer	"https://ntfy.sh"	Base URL of your ntfy server.
ntfyTopic	"" (empty)	Your private ntfy topic. Empty means phone push is off — desktop popups still work, nothing goes to your phone. See ntfy setup.

Declined invites are always skipped — there's no config knob for it.

state.json in the same folder tracks which occurrences already alerted (alertedKeys, pruned after 24h) and which are permanently ignored (ignoredKeys) — see the Configuration wiki page for the exact key format if you ever need to hand-edit it (e.g. to un-ignore something).

Filtering / ignoring events

• All-day events — skipped by default (ignoreAllDay).
• Keywords — add comma-separated substrings (Settings → Ignore, or ignoreKeywords) to skip any event whose title matches, e.g. focus time, lunch.
• Whole calendars — untick a calendar in Settings → Calendars to stop watching it entirely.
• Ignore forever — the popup/menu ignore button. On a recurring meeting it ignores the whole series (the button says "Ignore series"); on a one-off it ignores that occurrence.
• Pre-ignore — Settings → Ignore lists the next 7 days of meetings with per-row Ignore buttons (recurring ones offer "This time only" / "Whole series"), plus everything currently ignored with one-click un-ignore. Ignored meetings are excluded everywhere — alerts, menu bar, and the morning agenda.
• Declined invites — always skipped, no config needed.

Joining a meeting

If MeetAlert finds a Zoom, Google Meet, Microsoft Teams, Webex, Whereby, GoToMeeting, Jitsi, Chime, BlueJeans, or RingCentral link in the event's URL, location, or notes (checked in that order), the desktop popup, the ntfy push, and the menu bar all get a Join action — but they behave slightly differently. On the desktop popup, Join opens the link and acks in one step, same as Dismiss. On the phone push, Join only opens the link — it can't ack, since that kind of action never reports back to MeetAlert; use the ACK button on the push if you want to ack from your phone. In the menu bar, any upcoming meeting with a link is a clickable Join row — clicking it only opens the link, so the alerts for that meeting still fire as scheduled.

Morning agenda

• Morning agenda (agendaTime, off by default) — pick a time (to the minute) in Settings → Phone and MeetAlert pushes a single ntfy summary once a day: how many meetings, the first one, up to 6 upcoming, and your largest free gap before 7pm.

Testing

Set MEETALERT_TEST=1 to run a fully headless self-test: no calendar access is requested (no TCC prompt, no EventKit touched at all), and 10 seconds after launch it fires a synthetic [TEST] MeetAlert pipeline meeting 3 minutes out, with the escalation window forced to 20 seconds. State transitions print to stdout so you can watch the whole pipeline:

MEETALERT_TEST=1 build/MeetAlert.app/Contents/MacOS/MeetAlert
# fired a1b2c3d4
# acked a1b2c3d4      (if you click a button in the popup, or ACK the push)
# escalated a1b2c3d4  (if nothing acks it within 20s)

The token is a short hash of the alert's own key (meeting + offset), not a timestamp — it's just an opaque id shared between the "fired"/"acked"/"escalated" lines for the same alert.

Run the executable inside the built .app directly (not .build/release/MeetAlert, and not via open) so the bundle's Info.plist/LSUIElement context is intact and stdout stays attached to your terminal.

Test mode forces a few things for determinism: you're always treated as "present" (never away), the escalation loop caps at a single urgent resend instead of escalationRepeats, and the morning-agenda push is skipped entirely.

Google Calendar (and any other calendar)

MeetAlert doesn't talk to any calendar API — it reads whatever macOS's own EventKit already has, which is every calendar synced through System Settings → Internet Accounts: Google, iCloud, Exchange, CalDAV, whatever. Zero setup on MeetAlert's side.

The tradeoff is that you're at the mercy of macOS's own sync interval for that account. If last-minute meetings are showing up late, open Calendar.app → Settings → General and set "Refresh calendars" to Every minute. lateAlertMinutes exists specifically to cushion whatever lag remains.

Screenshots

Alerts settings	Phone settings

Feature requests and contributions

Have an idea for MeetAlert? Request a feature and say what you're trying to do; that matters more than the exact feature. Found a bug? Report it.

Code is welcome too: small, focused pull requests, and an issue first for anything bigger. See CONTRIBUTING.md.

Tipped on Ko-fi? Add your Ko-fi name to the request and it goes to the front of my queue. It's a thank-you, not a purchase: no promise on what ships or when.

More Mac apps by Roy

Free, open-source Mac menu-bar apps and terminal tools, all on one site: apps.roypadina.synology.me.

• NtfyBar — ntfy notifications on your Mac: popups that stay, rules, commands, plugins.
• Obsidian Vault Git Watcher — Never leave a vault uncommitted again.
• Window Organizer — Clear the desk in one keystroke.
• LanGuard — Wi-Fi off when you're wired. Back on when you're not.
• PullPing — Know when your pull requests need you, across every GitHub account.

Support

If MeetAlert saves you from walking into a meeting 10 minutes late, you can support its development — it's optional and always appreciated.

A ⭐ on the repo helps just as much.

License

MIT © 2026 Roy Padina