Ambient › Guides

How to get Claude Code notifications inside tmux

Updated · 4 min read

Inside tmux, Claude Code's desktop notifications never reach your terminal until you add set -g allow-passthrough on to ~/.tmux.conf and reload it. Hooks don't go through the terminal, so a Stop or PermissionRequest hook works in tmux as it is, and Ambient takes you back to the exact pane.

Let notifications through

Add these lines to ~/.tmux.conf, then run tmux source-file ~/.tmux.conf:

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

allow-passthrough lets Claude Code's notifications and progress bar reach the terminal outside tmux. The extended-keys lines make Shift+Enter insert a newline instead of sending your prompt. Your outer terminal still has to show notifications: Ghostty and Kitty do out of the box, iTerm2 after you enable escape-sequence alerts.

Let the bell flag the window

With "preferredNotifChannel": "terminal_bell" in ~/.claude/settings.json, Claude Code rings the bell when it finishes or waits for permission. tmux flags a window whose pane rang the bell in the status line, so you can see which window wants you even when it's in the background.

A hook that tells tmux

A hook runs inside the pane's environment, so it can ask tmux to show a message naming the window:

// ~/.claude/settings.json
{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "[ -n \"$TMUX\" ] && tmux display-message -t \"$TMUX_PANE\" 'Claude finished in #S:#I' || true", "async": true }] }
    ]
  }
}

#S:#I becomes the session and window number. Use the same command under PermissionRequest with different text to hear about permission requests the moment they happen.

Jump back to the pane

Ambient records the tmux pane each agent runs in. When one needs you, the notch island turns amber, and a click on the island, the banner or the menu bar row selects that exact pane. It works the same for cmux, and for Codex and Gemini CLI sessions.

Stop babysitting terminals.

Free for macOS 14 and later. Works with Claude Code, Codex and Gemini CLI.

Get Ambient

Common questions

Why don't Claude Code notifications show up in tmux?

tmux swallows the escape sequences Claude Code uses for notifications. Add set -g allow-passthrough on to ~/.tmux.conf and run tmux source-file ~/.tmux.conf.

Why does Shift+Enter send my prompt in tmux?

tmux can't tell Shift+Enter from Enter until extended keys are on. Add set -s extended-keys on and set -as terminal-features 'xterm*:extkeys' to ~/.tmux.conf.

Do hooks work inside tmux?

Yes. Hooks run as commands from Claude Code itself, not through the terminal, so they work in tmux without extra settings.

Sources

More guides: Multiple Claude Code sessions on Mac · Claude Code notifications on Mac