Notifications
Whenever something needs you, or a wait ends, heph sends one line out of its pane:
heph: main "add auth to the API..." -- approve cargo test 2>&1 | tail -20?
heph: main "add auth to the API..." -- asking "Which adapter is live?"
heph: main "add auth to the API..." -- review: 2 files, 3 hunks
heph: main "add auth to the API..." -- turn done, 1 file applied, $0.67
Each names the conversation and the first line of your prompt, so you know which piece of work is asking without going to look. Events within one second of each other become one message naming them all.
Nothing is sent for a pane you are looking at. Under tmux, heph asks tmux
whether its pane is the active pane of the active window of an attached client;
outside tmux, it uses the terminal's focus reporting. A turn that ends under
your eyes shows done on the status bar and nothing else.
[notify] suppress_focused = false turns this off.
Persistent desktop notifications
For notifications that remain until heph no longer needs you, enable the native freedesktop backend:
[notify]
desktop = true
channel = "none" # desktop only; leave command unset too
This uses the Linux desktop session's D-Bus notification service directly. No
libnotify or notify-send is needed. It can also run alongside the existing
terminal channel and command hook if you want both.
Heph requests no expiration and keeps one desktop notification per process, updating it as attention requests change:
-
Permissions and questions clear when answered or cancelled.
-
Reviews clear when resolved or put off, or when their turn ends.
-
Finished-turn notifications clear when the session starts new turn work, switches ref, or exits.
Quickly answered prompts disappear from the one-second delivery queue too. Focusing the pane suppresses new notices but does not clear an existing one. Dismissing a notification on the desktop does not cause heph to recreate it for that same condition; a new condition can notify again.
Your desktop daemon decides whether an unexpired notification stays visibly onscreen or lives in its notification center. Heph cannot force a pinned banner. If the service is unavailable, heph logs the failure and the TUI keeps working; terminal and command delivery are independent.
How it reaches you
Heph decides once, at startup, which channel this terminal answers to:
| Channel | When |
|---|---|
osc9 | The terminal is iTerm2, WezTerm, Ghostty, Kitty, or foot (by $TERM_PROGRAM and $TERM): a desktop notification through the terminal, no daemon. |
osc777 | The terminal is rxvt-unicode. |
tmux | Under tmux without allow-passthrough on, or under tmux in a terminal with no OSC support: the message shows in tmux's message line, in whichever window you are in. |
bell | Anything else: the terminal bell, which lights tmux's window flag and the terminal's urgency hint. |
Under tmux with set -g allow-passthrough on in your tmux.conf, the OSC
sequence passes through to the outer terminal and you get its notification.
[notify] channel forces a channel; "none" sends nothing.
[notify] command runs a program of yours in addition, for delivery outside the
terminal:
[notify]
command = "notify-send 'heph {project}/{ref}' '{message}'"
{event}, {ref}, {project}, and {message} are substituted. The
Notifications chapter lists the per-event switches.