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