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:
112
README.md
Normal file
112
README.md
Normal file
@@ -0,0 +1,112 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user