Files
luxe-macos-tray-notifier/README.md
cottongin ced6a44ed0 Add luxe Notifier: macOS menu bar app that tells you when luxe needs you
A luxe hook runs luxe-notify, which sends one JSON line over a Unix socket to
a SwiftUI menu bar app. The app shows a banner, keeps a badge count and
history, and brings the terminal forward when you click a banner.

Notifies on approvals (PermissionRequested), question prompts
(BeforeToolUse, matched to the question tool), errors, and turns that run at
least --min-seconds (default 30, timed from BeforeAgentStart to AgentEnd).

The menu warns when macOS has notifications blocked for the app. The app
writes status.txt beside its socket for debugging.

Known limits are in README.md and PLAN.md: a crowded menu bar can hide the
icon, and the first test build after a change can fail with a TestingMacros
error under Command Line Tools, which make test retries once.
2026-10-24 22:41:42 -04:00

4.5 KiB

luxe Notifier

A macOS menu bar app that tells you when luxe needs you. A luxe hook runs luxe-notify, which sends one JSON line over a Unix socket to the app. The app shows a macOS banner, keeps a badge count and a short history in the menu bar, and can mute banners. Clicking a banner or a history row brings your terminal to the front.

Install

make install
open ~/Applications/LuxeNotifier.app

This builds a release, puts luxe-notify in ~/.local/bin (make sure that's on your PATH), and installs an ad-hoc signed LuxeNotifier.app in ~/Applications. The first launch asks for notification permission. Turn on "Launch at login" in the menu if you want it.

Needs the Swift toolchain (Command Line Tools are enough).

If banners don't show, open the menu: a warning appears when macOS has notifications blocked for the app. Allow it under System Settings > Notifications.

Wire it into luxe

Add this to ~/.config/luxe/hooks.json:

{
  "PermissionRequested": [
    { "command": ["luxe-notify", "PermissionRequested"] }
  ],
  "BeforeAgentStart": [
    { "command": ["luxe-notify", "BeforeAgentStart"] }
  ],
  "BeforeToolUse": [
    { "matcher": "question", "command": ["luxe-notify", "BeforeToolUse"] }
  ],
  "AgentEnd": [
    { "command": ["luxe-notify", "AgentEnd", "--min-seconds", "30"] }
  ],
  "Error": [
    { "command": ["luxe-notify", "Error"] }
  ]
}

If luxe can't find luxe-notify, use its full path (/Users/you/.local/bin/luxe-notify).

  • PermissionRequested: luxe is waiting on an approval.
  • BeforeToolUse with "matcher": "question": luxe asked you a question. Keep the matcher: without it every tool call would run the hook. The banner shows the question text.
  • BeforeAgentStart: records when a turn begins. Sends nothing.
  • AgentEnd: a turn finished, so luxe is waiting for your next message. Only notifies if the turn took at least --min-seconds (default 30), so quick turns don't buzz you. If no start was recorded it notifies anyway.
  • Error: a turn failed.

luxe-notify always exits 0 and prints nothing to stdout, so it can never block or change a luxe call. If the app isn't running, it writes a one-line reason to stderr and moves on.

Options: --min-seconds N and --socket PATH, anywhere after the hook point.

Try it without luxe

echo '{"Other":{"tool":"bash"}}' | luxe-notify PermissionRequested

Debugging

The app writes ~/Library/Application Support/LuxeNotifier/status.txt with the notification permission state, the last event, and the last banner click. Start there if something is silent.

Known limits

  • A crowded menu bar can hide the icon. macOS drops status items that don't fit, and the app can't prevent it. Seen once: the item sat off-screen until other menu bar apps were quit. If the bell is missing, free up space or use a menu bar manager.
  • question prompts notify through the BeforeToolUse hook, which isn't documented as a question hook: it was found by logging real hook payloads. If a luxe update changes how question reports itself, those notifications could stop; PermissionRequested and AgentEnd would still work.
  • Clicking a banner brings the terminal app forward, not a specific window or tab. It needs the terminal's bundle id, which comes from the __CFBundleIdentifier or TERM_PROGRAM variables the hook inherits. With neither, the click does nothing. The app activates the terminal and also asks macOS to "reopen" it (what clicking its Dock icon does): activating alone gave Ghostty keyboard focus but left its window under other windows. Reopen never closes or quits anything, but what an app does with it is up to the app. Tested only with one Ghostty window and Finder in front; multiple windows, minimized windows and other terminals are untested. Clicking a history row uses the same code but was not tested.
  • Native banners only work from the installed .app. The bare binary falls back to osascript.

Uninstall

make uninstall

Remove the entries from hooks.json too.

Develop

make test      # 35 tests: hook parsing, socket round trip, menu model, turn timer, terminal lookup

On Command Line Tools without Xcode, the first test build after a change can fail with plugin for module 'TestingMacros' not found and then pass on retry. make test retries once for that exact error. The cause isn't known.

Code is split into NotifierCore (events, socket, menu model, timers), luxe-notify (the hook CLI), and LuxeNotifier (the SwiftUI app).