Claude Code notifications on Linux with notify-send
Updated
Quick answer
On a Linux desktop, a Stop hook that runs notify-send shows a notification when Claude Code finishes. Add a Notification hook for permission prompts. Both need a notification daemon, so they do nothing on a headless server: there, use a terminal sequence or a push to your phone.
Two hooks with notify-send
Claude Code runs hooks, commands listed in ~/.claude/settings.json, at fixed points of a session. Two of them cover notifications. Stop runs each time Claude finishes responding. Notification runs when Claude is waiting for you, and its notification_type field says why. One small script can serve both: it reads the JSON Claude Code sends on standard input and picks a title.
Save as ~/.claude/hooks/notify.sh, then chmod +x it
#!/bin/sh
# Claude Code hook: desktop notification on Linux. Reads the hook JSON on stdin.
input=$(cat)
project=$(basename "$(printf '%s' "$input" | jq -r '.cwd')")
if [ "$(printf '%s' "$input" | jq -r '.hook_event_name')" = "Stop" ]; then
notify-send -a "Claude Code" "Done · $project" \
"$(printf '%s' "$input" | jq -r '.last_assistant_message // ""' | head -c 200)"
else
notify-send -a "Claude Code" -u critical "Needs you · $project" \
"$(printf '%s' "$input" | jq -r '.message // ""')"
fi
exit 0
Merge into ~/.claude/settings.json
{
"hooks": {
"Stop": [
{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/notify.sh" }] }
],
"Notification": [
{
"matcher": "permission_prompt|elicitation_dialog",
"hooks": [{ "type": "command", "command": "~/.claude/hooks/notify.sh" }]
}
]
}
}
The matcher keeps the two notification types that mean Claude is blocked: a permission prompt and a form from an MCP server. Stop already covers the end of a turn, so idle_prompt, which fires about a minute after Claude finishes, would only repeat it. last_assistant_message is Claude’s final reply, which the hook can read without opening the transcript.
The script needs jq and notify-send. On Debian and Ubuntu, notify-send comes with the libnotify-bin package; other distributions ship it in their libnotify package. Run /hooks in Claude Code to check that both hooks are listed, then test the command alone with notify-send 'Claude Code' test.
One thing to know: Stop fires after every reply, including a one-line answer to a quick question. If that is too much, keep only the Notification hook during the day and add Stop for long sessions.
Add a sound
A notification is easy to miss on a second screen. On desktops that use PulseAudio, or PipeWire with its PulseAudio layer, paplay plays a file from the freedesktop sound theme. Add a line before exit 0:
In notify.sh
paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null &
Use a different file for the “Needs you” branch, such as bell.oga from the same folder, so you can tell the two apart without looking. The sound guide covers the terminal bell and the same hook on macOS and Windows.
Terminals that notify by themselves
Claude Code also has its own notifications, set by preferredNotifChannel. With the default, "auto", it sends a desktop notification when it detects Ghostty or Kitty, and does nothing in other terminals such as GNOME Terminal or Konsole. Set it to "terminal_bell" to ring the bell in any terminal, and let the terminal decide what a bell does: a sound, a flash, an urgent window.
In ~/.claude/settings.json
{
"preferredNotifChannel": "terminal_bell"
}
These built-in notifications fire only when you appear to be away: a permission prompt after about six seconds without a keystroke, a finished turn after about sixty. In Ghostty or Kitty, if you also add the hooks above, set preferredNotifChannel to "notifications_disabled" to avoid getting two alerts. Your hooks still run with that value.
A hook can also ask Claude Code to write a notification sequence for it, through the terminalSequence field of its JSON output: OSC 777 for Ghostty, urxvt and Warp, OSC 99 for Kitty. Hooks have no terminal of their own, so this is the supported way to reach it. It needs no notification daemon on the machine, which matters in the next case.
No desktop, no notification
notify-send talks to a notification daemon over the desktop session’s bus. A headless server, a container or a plain SSH session has none, and the command fails or does nothing. Anthropic’s hooks guide says so in as many words. Three ways around it:
- Over SSH, set
preferredNotifChannelon the server to your local terminal,"kitty","ghostty"or"iterm2". The sequence travels back through the connection and your local terminal shows it. - In tmux, sequences reach the outer terminal only with
set -g allow-passthrough on, and only from a pane you are looking at. - Detached, with nobody attached to the session, no sequence goes anywhere. Only a push over the network reaches you.
The SSH and tmux guide goes through each case with the configuration to copy.
On your iPhone
A desktop notification only helps while you are at the desk. Monish sends the same moments to your iPhone, from a desktop or from a server, and lets you answer them there.
On the Linux machine, with the 6-digit code from the app
curl -fsSL https://monish.cc/install.sh | sh -s 482913
The command installs the monish command, pairs the machine with your iPhone and adds Claude Code hooks to ~/.claude/settings.json, keeping a backup of the file. It needs no Node; with Node 18 or later, npx monish pair 482913 does the same. From then on, a permission request arrives with the exact command and two buttons, Allow and Deny; a question arrives with its options; a finished turn arrives with Claude’s last line, and a reply becomes its next instruction. The prompt also stays in your terminal, and the first answer wins.
Your notify-send hooks can stay: hooks for the same event run side by side. monish status checks the setup, and monish uninstall removes Monish’s hooks and unpairs the machine.
Questions
- Why does notify-send work in my terminal but not from the hook?
- Hooks inherit Claude Code’s environment, so if
notify-send 'Claude Code' testworks in the terminal where you startclaude, the command is fine. Check the script instead: is it executable, isjqinstalled, and does/hookslist it? - Will I get a notification after every reply?
- With a
Stophook, yes: it runs each time Claude finishes responding, not only when a long task ends. Keep only theNotificationhook if you want alerts when Claude is blocked. - Does this work under WSL?
- WSL has no Linux notification daemon of its own in most setups. Call
powershell.exefrom the hook so Windows shows the alert; it must be on your PATH through Windows interop. - Do I need a Claude plan for Monish on Linux?
- No. Hooks run on your machine, so Monish works the same whether Claude Code is signed in with a Claude plan, an API key or a cloud provider.
More guides
- Claude Code notifications over SSH and in tmuxAlerts from a server or a detached session, back to you.
- Play a sound when Claude Code finishesThe built-in bell, terminal by terminal, or a Stop hook that plays a sound.
- Claude Code on Windows: get notified when it’s doneA sound or a toast from PowerShell, natively or from WSL.
- Claude Code notifications not working: five causesIs the hook loaded, does it run, is it the right event.
New to Monish? The home page shows what lands on your iPhone, and all guides are listed here.
Get Monish on your iPhone
Free, no account. Your 6-digit code is waiting in the app.