# luxe Notifier: a macOS menu bar app for "luxe needs you" A native Swift/SwiftUI menu bar app that tells you when luxe is waiting on you. luxe hooks (`~/.config/luxe/hooks.json`) run a tiny CLI, `luxe-notify`, which sends one JSON line over a Unix socket to the app. The app posts a macOS notification, keeps a badge and a history list in the menu bar, and can bring the right terminal forward. Built with Swift Package Manager so everything builds and tests from the terminal. Decided with the user: menu bar app plus hook CLI, Swift and SwiftUI, Unix socket transport. Hook points used (from `luxe docs hooks`): `PermissionRequested` (approval prompt), `AgentEnd` (turn finished, waiting on your next message), `Error` (turn failed). Open item to verify in Phase 0: whether luxe's `question` tool fires any hook. ## Phase 0 — Verify hook behavior and scaffold Build: a SwiftPM package with three targets: `NotifierCore` (library), `luxe-notify` (CLI), `LuxeNotifier` (app). Write a throwaway hook that logs stdin to a file for `PermissionRequested`, `AgentEnd`, `Error`, and trigger each in luxe, including a `question` prompt. Done when: `swift build` succeeds; the logged payloads are saved under `docs/hook-payloads/`; `PLAN.md` is updated if the `question` tool fires no hook (then fall back to `AgentEnd`). ## Phase 1 — Event model and socket protocol (NotifierCore) Build: `NotifyEvent` (kind, title, message, cwd, timestamp, terminal hint) with JSON encode/decode, parsing from raw hook stdin, and a socket path helper (`~/Library/Application Support/LuxeNotifier/notify.sock`). Done when: `swift test` passes cases for each hook payload shape, malformed JSON (rejected with a clear error), and unknown event kinds (kept as a generic event, not dropped). ## Phase 2 — luxe-notify CLI Build: reads the hook event from stdin, maps it to a `NotifyEvent`, writes one JSON line to the socket, prints nothing on stdout (so luxe sees "no opinion"), and exits 0 even when the app isn't running (a hook must never block luxe). Failures go to stderr. Done when: `echo '' | swift run luxe-notify` delivers to a test listener (`nc -U`), and exits 0 with a stderr message when no socket exists. Tests cover both. ## Phase 3 — Menu bar app: listener and notifications Build: `MenuBarExtra` app that listens on the socket, posts a `UserNotifications` banner per event, and keeps an in-memory list. First launch requests notification permission. Done when: with the app running, the Phase 2 command shows a real banner; two quick events show two entries; the app handles a client disconnecting mid-write. Listener logic has unit tests. ## Phase 4 — Menu UI: badge, history, actions Build: badge count of unseen events, a history list (newest first, clear all), a click action that activates the terminal app owning the session, mute toggle, and launch at login. Done when: manual walkthrough passes (badge rises and clears, mute suppresses banners, click focuses the terminal) and logic is covered by view-model tests. ## Phase 5 — Install and wire into luxe Build: `make install` (builds release, copies `luxe-notify` to `~/.local/bin`, app to `~/Applications`), a documented `hooks.json` snippet, and a short README. Done when: from a clean state, a real luxe session raises a notification on a permission prompt and when a turn ends, and `README.md` has the exact install and uninstall steps. ## Follow-up work (done after the original six phases) Built and verified against the real app, with screenshots and the app's own `status.txt`: - Permission-denied warning in the menu (`BannerPermission`, unit-tested and mutation-checked). - Badge count next to the bell. - Turn-length suppression for `AgentEnd` (`TurnTimer`, `--min-seconds`, driven by `BeforeAgentStart`). - Click-to-focus: a banner click activates and reopens the terminal named by the event's `terminalBundleID`. Tested with one Ghostty window and Finder in front. - Question notifications: luxe's `question` tool fires `BeforeToolUse` (found by logging real hook payloads), parsed into a `question` event. Confirmed with a real banner. - Turn-length rule confirmed in real luxe: a 28s turn was suppressed, a 45s turn notified. Still open: - Clicking a history row (same code path as the banner, but not exercised). - Multiple windows, minimized windows and other terminals for click-to-focus. - The icon can be hidden by macOS on a crowded menu bar. No code fix known. - `TestingMacros` first-build error under Command Line Tools. `make test` retries once; cause unknown.