Notifications
insensical tells you when a pane needs you, so you can walk away from your agents and come back when it matters. You're told when a pane becomes waiting, done or failed, when a program sends a notification sequence, or when something runs isc notify TITLE [BODY].
With nothing attached, the daemon can run a command or post to a web address instead: see When nobody is attached.
- Panes that wait, fail or finish together are one notification, such as
10 panes failed. Click it to go to the first pane. - A finish is held for about 15 seconds. If you look at the pane or type in it first, you aren't told. An agent that pauses and wakes by itself isn't told of until it stops for good.
- A pane that says the same thing again isn't told of again until it says something different or you've looked.
- A pane that waits for you is never held back.
- You aren't told when you're looking at the pane, when it's muted, or when the cause is the bell.
Where you're told. With insensical in front, you get a notice inside the window and nothing on the desktop. Otherwise, or with no window open, you get a desktop notification.
The notice in the window sits at the foot of the sidebar, or over the window's bottom right corner when the sidebar is hidden or the tabs are along the top. It never resizes a terminal.
- It shows the state mark,
pane · projectand what the pane says. Click it to go to the pane;×closes it. - A finish goes after six seconds; a wait or failure stays until you've seen the pane.
- Three show at once; a line above them counts the rest and opens the overview.
- What the window says of no pane, such as "It could not be done" when the daemon refuses something you asked for and why, shows at the middle of the window's foot. It goes by itself after six seconds, or when you click it.
Sound. A pane that waits or failed makes a short sound of two rising notes. A finish makes a softer single note, if you ask for it.
sound | Plays |
|---|---|
needs-you (default) | Waiting and failed |
all | Waiting, failed and finished |
off | Nothing |
The settings sheet has a button to hear each. Linux needs pw-play, paplay or aplay, macOS uses afplay. You can't use sounds of your own.
Turning them off. notifications = false stops all of them. notify-waiting, notify-failed and notify-done turn off one kind each. Panes still show their state.
A desktop notification. Each pane has one, and a new one replaces the old. The title is project · pane; the body is what the program said, or "Waiting for you", "Done" or "Failed". A title is cut to 120 characters and the text to 600. They're sent at normal urgency, so do-not-disturb applies. Clicking one goes to the pane, restores it if it was minimized, and asks a window to come forward; with no window open, one opens on the pane. On Wayland the window may stay behind, though the pane is still selected. Hyprland brings it forward with misc:focus_on_activate on.
Muting a pane. Use the mute command in the palette (no default key), or isc mute [PANE] [--off]. The pane's states still show, and a mark appears in its header.
Muting a project. Use "Silence this project's notifications" in the palette (the mute-project command, no default key), or isc project mute NAME [--off]. No pane in the project sends a notification, including panes you open later. Panes muted on their own stay muted.
On Linux, a tray icon says what needs you, with no window open too. It has an amber dot while any pane waits or failed. Its menu lists those panes, and picking one goes to it. Quit insensical in the menu asks first and says which panes would end. The tray needs a desktop that shows status notifier items (GNOME needs the AppIndicator extension). tray = false takes the icon away; Show in the tray under Notifications in the settings is the same switch.
On macOS, notifications arrive even with the window closed. The system asks once whether to allow them. The menu bar and the Dock also say what needs you.
- The menu bar item counts panes that wait or failed, and its menu lists them.
- The Dock icon shows the same number as a badge. If it doesn't appear, turn on Badge application icon for insensical in System Settings, Notifications.
- At the top of Notifications in the settings, a line says whether macOS lets insensical notify you and badge its Dock icon. Open System Settings takes you there.
menu-bar = falseremoves the menu bar item anddock-badge = falsethe Dock number, both under Menu bar and Dock on Settings > General, a card only a Mac has.
When nobody is attached
An agent on a server stops to ask you something at two in the morning, and no window is open. The daemon can still tell you, by running a command of yours or posting to a web address of yours. Both go outward only: nothing listens.
The two settings belong to the daemon, so set them on the machine the agent runs on. From another machine, put --host NAME before each command.
isc config set notify-command /home/you/bin/tell-me
isc config set notify-url https://ntfy.sh/a-topic-only-you-knowSet one or both, then try them:
isc notify --testThat sends one through each, whoever is attached, and prints how it went:
notify-command: ran, exit status: 0, in 0.3 s
notify-url: posted, HTTP 200, in 0.4 sIt exits with an error if either failed. isc notify --sinks shows what's set, how the last one to each went, and how many weren't sent.
What gets sent is what would have been a notification, with the same mutes, switches and gathering. For several panes the title is the count, and the pane, project and program are the first pane's.
When it's sent. By default only when you're away: no window, terminal interface or browser is attached to that daemon. isc events, a script, a program in a pane and anything attached with only the look right don't count as someone being there. To be told every time:
isc config set notify-command-when always
isc config set notify-url-when alwaysThe command is a program and its arguments, cut at the spaces, with no shell: |, $VAR and quotes mean nothing. Put anything longer in a script and name the script. What happened is in the command's environment:
| Variable | What it holds |
|---|---|
INSENSICAL_EVENT | waiting, failed or done |
INSENSICAL_TITLE | project · pane, as on a notification |
INSENSICAL_BODY | What the pane says |
INSENSICAL_KIND | What a wait is for, if the program said: permission, question or auth. Otherwise empty |
INSENSICAL_PANE | The pane's number |
INSENSICAL_PROJECT | The project's name |
INSENSICAL_MACHINE | The name of the machine the daemon is on |
INSENSICAL_PROGRAM | The program in the pane |
A title or message is whatever a program wrote, so keep it in double quotes in your script: "$INSENSICAL_BODY". The rest of the environment is the daemon's, so an isc your script runs reaches the same daemon and, with INSENSICAL_PANE, acts on the pane the notification is about.
The web address is posted this, as JSON:
{"title": "api · claude", "message": "Wants permission: Allow edit to main.rs?",
"event": "waiting", "kind": "permission", "pane": 41, "project": "api",
"machine": "build", "program": "claude"}With notify-url-body = "text", the message alone is the body and the title goes in a Title header. Headers of your own go in a table of the settings file, or one at a time from the command line:
isc config set notify-url-headers "Authorization: Bearer tk_yourtoken"isc config get notify-url-headers shows each value masked, and isc config reset notify-url-headers takes them all out.
For a topic that needs you to sign in, give a token, or a user and password:
isc config set notify-url-token tk_yourtoken
isc config set notify-url-user me
isc config set notify-url-password "your password"Other users of the machine can read a command line while it runs, so give a secret on standard input: printf %s "$TOKEN" | isc config set --stdin notify-url-token reads the value to the end of its input, less one final newline.
A token is sent as Authorization: Bearer …, a user and password as Basic. With both set, the token is used, and either stands in place of an Authorization header you wrote. isc config get, isc notify --sinks and the settings sheets show only that a secret is set (a token by its last four characters).
Neither is sent over plain http:// to another machine, nor is an Authorization header you wrote: use an https:// address. An address on this machine (127.0.0.1, localhost, [::1]) may be http://. Keep the settings file to yourself (chmod 600).
Who sees the address and the command. Only a connection with the manage right sees both in full, which is every connection of your own unless you asked for fewer. Without it, such as a browser paired as a device that only looks, notify-url shows as its scheme and host (https://ntfy.sh) and notify-command as the program's name (tell-me).
ntfy. Pick a topic nobody would guess; it's the only secret. In the settings file on the machine the agent runs on:
notify-url = "https://ntfy.sh/a-topic-only-you-know"
notify-url-body = "text"
[notify-url-headers]
Priority = "high"
Tags = "robot"Subscribe to the topic in the ntfy app, then run isc notify --test.
Pushover, Telegram, Slack and anything else want a body of their own shape, so let curl shape it in the command. For Pushover, save this as /home/you/bin/tell-me and chmod +x it:
#!/bin/sh
exec curl -fsS --max-time 8 \
--form-string "token=YOUR_APP_TOKEN" \
--form-string "user=YOUR_USER_KEY" \
--form-string "title=$INSENSICAL_TITLE" \
--form-string "message=$INSENSICAL_BODY" \
https://api.pushover.net/1/messages.jsonThen isc config set notify-command /home/you/bin/tell-me and isc notify --test.
A desktop you're logged in to, with a daemon that can't reach it. A daemon started over ssh doesn't know the desktop's session; tell notify-send where it is:
#!/bin/sh
export DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/$(id -u)/bus"
exec notify-send --app-name=insensical "$INSENSICAL_TITLE" "$INSENSICAL_BODY"Good to know.
- A window left open while you're at lunch counts as you being there. Use
alwaysto have your phone told too. - The command and the address each get ten seconds. The command runs in your home directory, so name it by its full path:
~isn't expanded, and a path with a space can't be named. - Four are sent at once at most. One more is dropped and counted, and
isc notify --sinksshows the count. httpstrusts the authorities built intoisc, not your system's. For a certificate of your own making, use the command withcurl.httpsneeds an x86-64 processor from about 2014 or later, or an ARM one with the AES and SHA-2 extensions (a Raspberry Pi 4 lacks them). Use the command withcurl, or plainhttp.- To post through a proxy, start the daemon with
ALL_PROXY,HTTPS_PROXYorHTTP_PROXYin its environment, andNO_PROXYfor hosts to reach directly. See The daemon's environment.