Files
luxe-macos-tray-notifier/PLAN.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 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.