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.
This commit is contained in:
2026-10-24 22:41:42 -04:00
commit ced6a44ed0
30 changed files with 1314 additions and 0 deletions

72
PLAN.md Normal file
View File

@@ -0,0 +1,72 @@
# 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 '<payload>' | 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.