Send a desktop notification from a script, and wait for the answer
A long build, a deploy or a nightly job should be able to tell you it finished, and sometimes ask you a question. With QNotch running, any script can post a notification to the notch with one command, add buttons and wait for your answer.
Post a notification
On Windows, call QNotch.exe notify with a title and an optional body:
QNotch.exe notify "Build finished" "142 tests passed" --app Build --level success
QNotch.exe notify "Deploy failed" --app CI --level error --url https://example.com/reportOn a Mac, the command is the app's own executable:
/Applications/QNotch.app/Contents/MacOS/QNotch notify "Build finished" "142 tests passed" --app Build --level successThe notification shows as a toast at the notch, adds to the unread count and stays in the Notifications tab. --level is info, success, warning or error. --url adds a button that opens a link. Run notify --help for the full list.
Ask a question and wait for the answer
Add up to three buttons with --action id=Label. The command then waits until you click one, and prints the id of the button you clicked:
$answer = QNotch.exe notify "Run the tests?" --action approve=Approve --action deny=Deny
if ($answer -eq "approve") { npm test }The exit code says what happened:
| Exit code | Meaning |
|---|---|
0 | Sent, or answered |
1 | Dismissed |
2 | Timed out |
3 | QNotch is not running |
4 | Error |
On Windows, QNotch.exe is a GUI program, so an interactive shell does not wait for it. Capture the output, as above, when you need the answer. Scripts and hooks that capture output wait as usual.
Without the command line
The same JSON message goes in three ways, so anything that can open a pipe, a socket or an HTTP connection can post.
| Way | Windows | Mac |
|---|---|---|
| Command line | QNotch.exe notify | QNotch notify, in QNotch.app/Contents/MacOS |
| Local pipe or socket | \\.\pipe\QNotch.Notify | notify.sock in ~/Library/Application Support/QNotch.Mac |
| Local HTTP | POST http://127.0.0.1:47821/notify, with a bearer token | |
curl -X POST http://127.0.0.1:47821/notify \
-H "Authorization: Bearer <token>" \
-d '{"title":"Deploy done","app":"CI","level":"success"}'HTTP answers only on this computer and needs the token from Settings, Notifications. Requests from web pages, which carry an Origin header, are refused. Add ?wait=1 to wait for an answer.
Update a notification in place
Post again with the same id and the notification is replaced, which makes a progress display:
{ "id": "build-42", "app": "Build", "title": "Building", "body": "Step 3 of 7" }What a button can do
- Open a link: http, https, vscode, vscode-insiders, cursor or claude.
- Bring a window forward:
--focusadds a button back to the terminal that posted the notification. - Answer a waiting request: a button with neither only reports that it was clicked.
No button can run a program. That is deliberate: a notification is something another process sent you.
Good to know
- While an app uses your microphone, notifications stay quiet and go straight to the history. One that waits for an answer still shows, because someone is waiting on it.
- An error opens the panel, except in Game mode or during a call. You can turn that off.
- Titles are capped at 80 characters and bodies at 300. Each app gets one toast per second; the rest go to the history.
- Mute an app, change how long toasts show and how long history is kept in Settings, Notifications.
The notifications reference has the full message format. To follow Claude Code and Codex sessions instead of posting your own, see See when Claude Code or Codex is waiting for you.