# 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 ```bash 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`: ```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 ```bash 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 ```bash make uninstall ``` Remove the entries from `hooks.json` too. ## Develop ```bash 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).