Claude Code notifications over SSH and in tmux
Updated
Quick answer
When Claude Code runs on a server over SSH, or in a detached tmux session, a desktop notification has no desktop to appear on. Two things still work: a terminal sequence that travels back through SSH to your local terminal, and a push sent from the server to your phone, which reaches you even when no terminal is attached.
Why desktop hooks fail on a server
Hooks run on the machine where Claude Code runs. A hook that calls osascript, notify-send or PowerShell shows its alert on that machine’s screen, and a server has no screen. On Linux, notify-send also needs a desktop notification daemon, which headless servers and SSH sessions don’t have: the command fails quietly and the hook looks broken.
So the alert has to come back to you another way. Either through the terminal connection you already have open, as an escape sequence your local terminal turns into a notification, or over the network, as a push that does not depend on any terminal at all.
Sequences that travel over SSH
Escape sequences travel through SSH like any other text, so your local terminal receives what Claude Code writes on the server. The simplest setup needs no hook: on the server, set preferredNotifChannel to the terminal you use locally.
In ~/.claude/settings.json on the server: "ghostty", "kitty" or "iterm2"
{
"preferredNotifChannel": "ghostty"
}
Ghostty and Kitty forward the notification to your system without further setup. iTerm2 needs two switches: under Settings › Profiles › Terminal, check Notification Center Alerts, then in Filter Alerts enable Send escape sequence-generated alerts. With "terminal_bell" instead, any local terminal that handles the bell character will do.
These built-in notifications come when Claude finishes or waits for a permission and you appear to be away. For a message of your own, a hook returns the sequence in the terminalSequence field of its JSON output and Claude Code writes it for you. A hook has no terminal, so writing to /dev/tty fails; this field is the supported route. It accepts OSC 9 (iTerm2, WezTerm, Windows Terminal), OSC 99 (Kitty), OSC 777 (Ghostty, urxvt, Warp) and the bell.
A Notification or Stop hook for Ghostty or Warp (OSC 777)
#!/bin/sh
# Claude Code hook on the server: a desktop notification on your local terminal, through SSH.
input=$(cat)
project=$(basename "$(printf '%s' "$input" | jq -r '.cwd')")
msg=$(printf '%s' "$input" | jq -r '.message // "Finished"')
seq=$(printf '\033]777;notify;Claude Code · %s;%s\007' "$project" "$msg")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'
The limits are those of the connection. Claude Code writes the sequence only in an interactive session with its interface open, and not from a hook marked async. And the sequence reaches you only while your terminal window is open and connected.
tmux and screen
Inside tmux, sequences stop at tmux unless you let them through. With tmux 3.3 or later, add this line and reload with tmux source-file ~/.tmux.conf:
In ~/.tmux.conf
set -g allow-passthrough on
With on, only the panes tmux is showing can send a sequence. On tmux 3.4 or later, all lets the other panes of a session you are attached to send them too. In GNU screen, keep Claude Code’s window showing: a background window’s sequences don’t reach your terminal. With "terminal_bell", tmux also marks the window that rang in its status line, which helps with several sessions in one server.
tmux is also how a session survives you leaving. Run straight in the SSH shell, Claude Code stops when the connection drops; started in tmux or screen and detached, it keeps working. Anthropic’s Remote Control docs give the same advice for remote machines.
A detached session: push to your phone
This is the common case: Claude Code works in a detached tmux session on a server while your laptop is closed. No client is attached, so there is no terminal to carry a sequence, and the server has no desktop. Only a push sent over the network reaches you, and three kinds exist:
- A one-way push from a hook, through ntfy or a chat webhook. Free and quick to set up; you still reconnect to answer.
- Remote Control with the Claude app, if the session is connected to it and you have a Claude plan with a claude.ai sign-in.
- A notifier app that sends the request to your phone and hands your answer back to the session.
Whatever you choose, the permission prompt stays in the tmux pane. When you reattach, you find it where Claude left it, or already answered.
Pair a server with a code
Monish works the same on a server as on a laptop. Open Monish on your iPhone, then, in your SSH session:
On the server, with the 6-digit code from the app
curl -fsSL https://monish.cc/install.sh | sh -s 482913
The command adds Claude Code hooks to the server’s ~/.claude/settings.json. From then on the hooks send each request over HTTPS from the server itself, so nothing has to be attached: a permission request reaches your lock screen with the command and Allow and Deny, and a finished turn arrives with a Reply action. The server needs curl and outbound HTTPS.
The prompt stays in the tmux pane while your iPhone has it, and the first answer wins. Your iPhone can answer within the answer window set in the app’s Settings, 10 minutes by default; after that, Claude Code asks you in the pane. Each server appears in the app as its own computer, and monish status checks the setup.
Questions
- Does Claude Code keep running when I close the SSH connection?
- Not if it runs straight in the SSH shell: it stops with the connection. Start it inside tmux or screen and detach, and it keeps working on the server.
- Why do I only get notifications from the pane I’m looking at?
- With
allow-passthrough on, tmux lets only visible panes send escape sequences. Useall, on tmux 3.4 or later, to let every pane of a session you are attached to send them. - Can several servers reach the same iPhone?
- Yes. Pair each one with its own code. Each appears in the app under its own name, and every notification names the project it comes from.
- Does a push from the server work with an API key?
- Yes. Hooks run on the server whatever Claude Code is signed in with, so Monish works with a Claude plan, an API key or a cloud provider.
More guides
- Claude Code notifications on Linux with notify-sendTwo hooks for a Linux desktop, and what to do on a headless server.
- Claude Code notifications with ntfyA push to your phone from one curl line, and what a one-way push leaves out.
- Parallel Claude Code sessions: tell them apartName sessions and tabs, and know which one needs you.
- Claude Code push notifications not working on iPhoneWhat Remote Control needs, and six things to check.
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.