Files
luxe-macos-tray-notifier/README.md

113 lines
4.5 KiB
Markdown
Raw Normal View History

# 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).