Claude Code in tmux or screen: getting notified from a detached session

01Attached: let notifications through tmux

tmux sits between Claude Code and your terminal and, by default, swallows the escape sequences Claude Code uses for desktop notifications. Anthropic's terminal guide gives this block for ~/.tmux.conf:

set -g allow-passthrough on
set -g focus-events on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

Apply it to the running server:

tmux source-file ~/.tmux.conf

allow-passthrough lets notifications and progress updates reach the outer terminal. The other lines fix Shift+Enter for newlines. With this in place, terminals that show Claude Code's notifications outside tmux (Ghostty, Kitty, and iTerm2 with alerts enabled) show them inside tmux too.

The same applies to hooks that return a terminalSequence. Anthropic's hooks reference says Claude Code writes these sequences itself, which works inside tmux and GNU screen. The macOS, Linux and SSH guides have examples.

02Attached, but in another window: use the bell

If Claude Code runs in one tmux window and you work in another, the bell is a simple signal. Tell Claude Code to always send one:

{
  "preferredNotifChannel": "terminal_bell"
}

Then make tmux act on it, in ~/.tmux.conf:

setw -g monitor-bell on
set -g bell-action other
set -g visual-bell off

monitor-bell (on by default) flags a window that rang its bell, and tmux marks it with ! in the status line. bell-action other passes bells from windows other than the one you are looking at on to your terminal, so the terminal can beep or bounce. Use any to include the current window too. Setting visual-bell to on shows a message in tmux instead of passing the bell on.

03Say which session needs you

With several sessions running, a notification that just says "Claude needs you" is not much help. A hook runs inside the pane's environment, so it can ask tmux for the session and window name. This Linux example shows them in a desktop notification:

#!/bin/bash
msg=$(jq -r '.message // "Claude Code needs your attention"')
where=""
if [ -n "$TMUX_PANE" ]; then
  where=$(tmux display-message -p -t "$TMUX_PANE" '#S:#W')
fi
notify-send "Claude Code ${where}" "$msg"

Save it as ~/.claude/hooks/notify-tmux.sh, run chmod +x on it and use it as a Notification or Stop hook command. #S is the session name and #W the window name; name your sessions with tmux new -s api-refactor and the notification tells you where to go. Swap notify-send for your platform's command, or for a push. The multiple sessions guide has more ways to tell sessions apart.

04Detached: you need a push

Detaching is the point of tmux: you start a long task, detach, and go. Claude Code keeps working in the detached session. But there is now no terminal to show an escape sequence or a bell, and if the tmux server was started over SSH, a desktop notification command may have nowhere to go either.

A hook that makes a network request does not care whether anyone is attached. Any push service works. The ntfy guide and the Telegram, Slack and Discord guide have hooks you can paste. These tell you something happened; they cannot answer Claude, so a permission prompt still waits until you reattach with tmux attach -t api-refactor.

05Where Claude Code Notifier fits

Claude Code Notifier is an independent tool (made by TouchTap, not by Anthropic) built on Claude Code's hooks. Its free command line tool, ccn, runs on Mac, Windows and Linux. Because it hooks into Claude Code rather than into a terminal, it works the same in tmux, screen or a plain shell, attached or detached:

curl -fsSL https://claudecodenotifier.com/install.sh | sh

On a desktop machine it shows a desktop notification when Claude finishes, needs a permission or asks a question. Pair a phone and the same events arrive as push notifications through TouchTap's encrypted relay, from any machine ccn runs on, including a server you reached over SSH.

The phone closes the gap a detached session leaves. When a permission comes up, you can allow once, allow for the session or deny from the phone, and Claude carries on without you reattaching. You can pick an answer when Claude asks a question, and send the next instruction right after Claude finishes. If you typed in the last 30 seconds, nothing waits for the phone and the terminal asks as usual. If you are away, the terminal waits for the phone's answer up to a ceiling you choose (hold_ceiling_seconds), and stops waiting the moment you touch the keyboard.

See pairing a phone, walking away from long tasks and the ccn page. The phone apps need a subscription or lifetime purchase; see pricing.

06GNU screen

screen works much like tmux for this. Anthropic's hooks reference says hook terminalSequence output works inside screen, and screen shows a message when a window you are not looking at rings its bell. Detached screen sessions have the same problem as detached tmux: nothing is on screen, so use a push.

07FAQ