Per-project folder for work summaries written after multi-file tasks. Kept out of the repo.
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.BeforeToolUsewith"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.
questionprompts notify through theBeforeToolUsehook, which isn't documented as a question hook: it was found by logging real hook payloads. If a luxe update changes howquestionreports itself, those notifications could stop;PermissionRequestedandAgentEndwould 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
__CFBundleIdentifierorTERM_PROGRAMvariables 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 toosascript.
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).