73 lines
4.5 KiB
Markdown
73 lines
4.5 KiB
Markdown
|
|
# 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.
|