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:

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. Use all, 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

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.

Download on the App Store