Notifications
Get pinged when Claudin needs you — through whatever channel your terminal and OS support.
Overview
Claudin surfaces "needs attention" events — input required, long task finished, custom hook-driven events — through the best channel available in your environment. The router picks automatically by default, and you can override it via /config at any time.
Identical notifications fired within 2 seconds are coalesced, so you won't get spammed when several tools complete in quick succession.
Channels
Configured via preferredNotifChannel in ~/.claudin/settings.json — or pick interactively under /config → Notifications.
| Channel | What it does |
|---|---|
auto | Pick the best available channel for the detected terminal/OS (default). |
iterm2 | iTerm2 proprietary OSC 9 sub-protocol. |
iterm2_with_bell | iTerm2 OSC 9 + raw BEL. |
kitty | Kitty OSC 99 (3-part: title / body / focus). |
ghostty | Ghostty OSC 777 notify;…. |
os_native | Desktop toast via notify-send / osascript / Windows Toast XML. |
terminal_bell | Raw \x07 BEL. |
notifications_disabled | No-op. |
Auto resolution
The auto channel walks this decision tree:
- Headless (
!process.stdout.isTTY) →os_native(no terminal to talk to). - OSC channel from the terminal matrix below, if one matches.
- Apple Terminal → try
os_native(toast), else BEL if the user's Profile has Bell enabled. - SSH session without WSL → skip OS-native (a toast on the remote host is invisible). The terminal-side OSC paths still work — the escape travels over the tty to your local emulator.
- Otherwise →
os_native.
Terminal → channel matrix
| Terminal | Channel chosen by auto |
|---|---|
| iTerm2 | iterm2 |
| kitty | kitty |
| Ghostty | OSC 777 |
| WezTerm | OSC 777 |
| foot (Wayland) | OSC 777 |
| urxvt / rxvt | OSC 777 |
| Windows Terminal | OSC 9 plain (WT renders raw OSC 9 as a toast) |
| ConEmu | OSC 9 plain |
| Apple Terminal | os_native (osascript) → fallback BEL |
| Alacritty | os_native |
| GNOME Terminal / Konsole / Terminator / Tilix / xterm | os_native |
| Anything else | os_native (best-effort) |
OS-native backends
| Platform | Primary | Fallback |
|---|---|---|
| macOS | terminal-notifier (if installed via brew) | osascript -e 'display notification …' |
| Linux | notify-send (libnotify) | kdialog --passivepopup |
| Windows 10/11 | powershell.exe Toast XML via -EncodedCommand (built-in WinRT, no module dep) | — |
| WSL | Same Toast XML over powershell.exe interop | — |
The Windows Toast payload is base64-encoded as UTF-16LE before being passed to powershell.exe -EncodedCommand — that avoids both XML and shell-quoting pitfalls. AppleScript and Toast XML payloads are escaped accordingly.
Hooks
Before routing to the channel above, Claudin fires executeNotificationHooks(). That lets you wire any custom backend — Slack, Pushover, ntfy, an internal webhook — via the hooks section of ~/.claudin/settings.json. The channel runs in addition to, not instead of, the hook.
Useful when you want both a desktop toast and a Slack DM, or when you're on a remote box and want the notification to reach your phone instead.
Configuration
Open /config inside the Claudin REPL and pick a channel under Notifications. Or edit ~/.claudin/settings.json directly:
{
"preferredNotifChannel": "auto"
}Set to any of the channels listed above. Omit the key (or leave it at auto) for automatic detection.