在 tmux 或 screen 中使用 Claude Code：從 detached session 接收通知

01Attach 狀態：讓通知穿過 tmux

tmux 夾在 Claude Code 與你的 terminal 之間，預設會吃掉 Claude Code 用來發送桌面通知的 escape sequence。Anthropic 的 terminal 指南提供了以下 ~/.tmux.conf 設定：

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

套用到正在執行的 server：

tmux source-file ~/.tmux.conf

allow-passthrough 讓通知與進度更新能傳到外層 terminal，其他幾行則修正用 Shift+Enter 換行的問題。設定完成後，原本在 tmux 外就能顯示 Claude Code 通知的 terminal（Ghostty、Kitty，以及啟用警示的 iTerm2），在 tmux 裡也能顯示。

回傳 terminalSequence 的 hook 也一樣。根據 Anthropic 的 hooks 參考文件，這些 sequence 由 Claude Code 自行寫出，因此在 tmux 和 GNU screen 裡都能運作。範例請見 macOS、Linux 與 SSH 指南。

02已 attach 但在其他視窗：使用 bell

如果 Claude Code 在某個 tmux 視窗執行，而你在另一個視窗工作，bell 是個簡單的訊號。設定 Claude Code 一律發出 bell：

{
  "preferredNotifChannel": "terminal_bell"
}

接著在 ~/.tmux.conf 中讓 tmux 對它做出反應：

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

monitor-bell（預設開啟）會標記響過 bell 的視窗，tmux 會在狀態列用 ! 標示。bell-action other 會把你目前所在視窗以外的 bell 轉給 terminal，讓 terminal 發出提示音或跳動圖示。改用 any 則連目前視窗也包含在內。將 visual-bell 設為 on 時，tmux 會改為顯示訊息，而不轉送 bell。

03標明是哪個 session 需要你

同時跑好幾個 session 時，只寫著「Claude 需要你」的通知幫助不大。hook 是在 pane 的環境中執行，因此可以向 tmux 查詢 session 和視窗名稱。這個 Linux 範例會把它們顯示在桌面通知中：

#!/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"

將它存成 ~/.claude/hooks/notify-tmux.sh，執行 chmod +x，再設為 Notification 或 Stop hook 的指令。#S 是 session 名稱，#W 是視窗名稱；用 tmux new -s api-refactor 為 session 命名，通知就會告訴你該去哪裡。你也可以把 notify-send 換成你平台上的指令，或換成 push。多 session 指南中還有更多區分 session 的方法。

04Detached 狀態：你需要 push

Detach 正是 tmux 的重點：啟動長時間任務、detach，然後離開。Claude Code 會在 detached session 中繼續工作。但這時已經沒有 terminal 能顯示 escape sequence 或 bell；如果 tmux server 是透過 SSH 啟動的，桌面通知指令可能也無處可送。

發出網路請求的 hook 不在乎有沒有人 attach，任何 push 服務都可以。ntfy 指南以及 Telegram、Slack 與 Discord 指南都有可直接貼上的 hook。這些方式只能告訴你發生了什麼事，無法回覆 Claude，所以權限 prompt 仍會等到你用 tmux attach -t api-refactor 重新 attach 為止。

05Claude Code Notifier 的角色

Claude Code Notifier 是建構在 Claude Code hook 之上的獨立工具（由 TouchTap 開發，並非 Anthropic 出品）。它的免費命令列工具 ccn 可在 Mac、Windows 和 Linux 上執行。由於它掛在 Claude Code 上而不是 terminal 上，無論在 tmux、screen 或一般 shell，attach 或 detach，運作方式都一樣：

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

在桌機上，Claude 完成工作、需要權限或提出問題時，它會顯示桌面通知。配對手機後，同樣的事件會透過 TouchTap 的加密 relay 以 push 通知送達，來源可以是任何執行 ccn 的機器，包括你透過 SSH 連上的伺服器。

手機補上了 detached session 留下的缺口。出現權限請求時，你可以直接在手機上選擇允許一次、在本次 session 中允許或拒絕，Claude 就會繼續執行，不必重新 attach。Claude 提問時你可以選擇答案，完成工作後也能立刻送出下一個指令。如果你在最近 30 秒內有打字，就不會等待手機，terminal 會照常詢問。如果你不在電腦前，terminal 會等待手機的回覆，最長等到你設定的上限（hold_ceiling_seconds），而且只要你一碰鍵盤就會停止等待。

請參閱配對手機、離開電腦執行長時間任務與 ccn 頁面。手機 App 需要訂閱或買斷；詳見價格方案。

06GNU screen

在這方面，screen 的運作跟 tmux 差不多。Anthropic 的 hooks 參考文件指出，hook 的 terminalSequence 輸出在 screen 裡可以運作；當你沒在看的視窗響起 bell 時，screen 也會顯示訊息。Detached 的 screen session 和 detached 的 tmux 有同樣的問題：畫面上什麼都沒有，所以請使用 push。

07常見問題