Notify — Tmux Notifications via File Protocol
Send notifications to the user through tmux by writing a JSON request file. A Claude Code hook detects the write and routes the notification through the appropriate tmux channels.
Usage
Read ~/.claude/skills/runtime.json to get the runtime_dir value, then write to <runtime_dir>/claude-panes/notify.json:
{
"level": "alert",
"message": "tests failed",
"title": "agent",
"duration": 5000,
"target": ""
}
Fields
| Field | Default | Description |
|---|---|---|
level |
(required) | info, status, alert, system, or clear |
message |
(required except clear) |
Notification text |
title |
"agent" |
Title for system-level desktop notifications |
duration |
5000 |
Display duration in ms (for info level) |
target |
current session | Target session name, or "parent" for parent-session routing |
Severity Levels
| Level | Channel(s) | When to use |
|---|---|---|
info |
Transient status-line flash | Routine progress |
status |
Persistent status bar text | Ongoing state |
alert |
Status bar + bell | Demands attention |
system |
Alert + desktop notification | Left the terminal |
clear |
Unsets status bar text | Condition resolved |
Dependencies
- tmux (required)
notify-send(optional, Linux desktop notifications)osascript(optional, macOS desktop notifications)- Claude Code hooks configured (run
setup.shonce)