Thông báo Claude Code trên Linux

01Claude Code tự làm được gì

Khi Claude làm xong một tác vụ hoặc đang chờ cấp quyền mà bạn có vẻ không ở đó, Claude Code sẽ phát ra một sự kiện thông báo. Theo hướng dẫn terminal của Anthropic, Ghostty và Kitty biến sự kiện này thành thông báo desktop; các terminal khác như GNOME Terminal, Konsole hay terminal của VS Code thì không hiện gì cả.

Thay vào đó, bạn có thể yêu cầu bell ở bất kỳ terminal nào:

{
  "preferredNotifChannel": "terminal_bell"
}

Bell hoạt động thế nào tùy vào terminal và desktop: có thể kêu bíp, nháy sáng hoặc đánh dấu cửa sổ là cần chú ý. Hướng dẫn terminal bell có nói rõ phần này. Muốn có thông báo thật sự thì hãy dùng hook.

02Cài notify-send

Kiểm tra xem máy đã có chưa:

notify-send 'Claude Code' 'test'

Nếu không tìm thấy lệnh, hãy cài nó:

sudo apt install libnotify-bin   # Debian, Ubuntu, Mint
sudo dnf install libnotify       # Fedora, RHEL
sudo pacman -S libnotify         # Arch

Nếu lệnh chạy được mà không thấy gì hiện ra, tức là bạn chưa có notification daemon. GNOME, KDE Plasma, Cinnamon và Xfce đều có sẵn. Với tiling window manager như Sway, i3 hay Hyprland, bạn cần tự cài và khởi động một daemon, ví dụ mako hoặc dunst. Cả Wayland và X11 đều được, vì notify-send giao tiếp với daemon qua D-Bus chứ không phải với màn hình.

03Một Notification hook

Đây là ví dụ cho Linux trong hướng dẫn hook của Anthropic. Thêm nó vào ~/.claude/settings.json, cạnh các key bạn đã có:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

Gõ /hooks trong Claude Code để thấy nó nằm dưới Notification. Matcher rỗng sẽ kích hoạt với mọi loại thông báo. Các loại chính là permission_prompt, khi một yêu cầu duyệt đã chờ khoảng sáu giây mà bạn không gõ gì, và idle_prompt, khoảng 60 giây sau khi Claude xong việc. Hướng dẫn Notification hook có danh sách đầy đủ.

04Biết ngay khi Claude làm xong

idle_prompt đến trễ một phút. Hook Stop thì chạy ngay khi Claude kết thúc lượt của mình, và không cần matcher:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send -a 'Claude Code' 'Claude Code' 'Claude has finished'"
          }
        ]
      }
    ]
  }
}

-a đặt tên app mà daemon hiển thị. Một số tùy chọn hữu ích khác: -u critical giữ thông báo trên màn hình cho đến khi bạn tắt nó (với hầu hết daemon), và -i dialog-information thêm icon. Xem thêm về sự kiện này trong hướng dẫn Stop hook.

05Hiện nội dung thật, kèm âm thanh

Hook nhận JSON qua standard input, và input của Notification có trường message. Một script có thể hiển thị nội dung đó và phát âm thanh. Lưu đoạn sau thành ~/.claude/hooks/notify-linux.sh:

#!/bin/bash
msg=$(jq -r '.message // "Claude Code needs your attention"')
notify-send -a 'Claude Code' 'Claude Code' "$msg"
paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null || true

Cấp quyền thực thi bằng chmod +x ~/.claude/hooks/notify-linux.sh rồi dùng ~/.claude/hooks/notify-linux.sh làm lệnh của hook. jq có sẵn trong kho package của mọi distro. paplay chạy được với PulseAudio và lớp PulseAudio của PipeWire, còn file âm thanh lấy từ freedesktop sound theme (sound-theme-freedesktop trên Debian và Ubuntu). Bạn có thể dùng bất kỳ file .oga hay .wav nào.

06Không có notify-send? Dùng escape sequence

Nếu terminal của bạn hiểu escape sequence cho thông báo, hook có thể nhờ Claude Code gửi giúp. Hook không có terminal riêng, nên bạn trả sequence về trong trường terminalSequence và Claude Code sẽ ghi nó ra. Tài liệu tham khảo của Anthropic liệt kê OSC 777 cho Ghostty, urxvt và Warp, và OSC 99 cho Kitty. Ví dụ:

#!/bin/bash
body=$(jq -r '.message // "Needs your attention"')
seq=$(printf '\033]777;notify;%s;%s\007' "Claude Code" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

Cách này không cần daemon trên máy chạy Claude Code, nên đây cũng là mẹo dùng cho server từ xa qua SSH.

07Khi notify-send chạy được trong shell nhưng không chạy từ Claude Code

notify-send cần địa chỉ D-Bus session của phiên đăng nhập desktop. Hook kế thừa môi trường của Claude Code, nên nếu Claude Code được mở từ terminal trên desktop thì không sao. Nhưng nếu Claude Code chạy qua SSH, từ một systemd service, trong container, hoặc trong một tmux server được khởi động lần đầu từ SSH, thì có thể thiếu địa chỉ này và thông báo sẽ không đi đâu cả. Hãy chạy echo $DBUS_SESSION_BUS_ADDRESS trong chính shell bạn dùng để chạy claude; nếu kết quả rỗng, thông báo desktop từ phiên đó sẽ không hiện. Hướng dẫn tmux và hướng dẫn SSH có nói về các trường hợp này.

08Claude Code Notifier nằm ở đâu trong bức tranh này

Các hook ở trên là lựa chọn tốt khi bạn ngồi tại máy. Nhưng khi bạn rời bàn thì chúng không báo được cho bạn, và thông báo desktop cũng không thể dùng để trả lời Claude.

Claude Code Notifier là một công cụ độc lập (do TouchTap phát triển, không phải Anthropic) xây dựng trên hook của Claude Code. Công cụ dòng lệnh miễn phí của nó, ccn, chạy trên Mac, Windows và Linux. Trên Linux:

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

hoặc npx @touchtap/ccn nếu bạn có Node.js. Nó thêm các hook của mình vào ~/.claude/settings.json, giữ nguyên mọi thứ khác và tạo bản sao lưu. Từ đó, nó sẽ hiện thông báo desktop trên Linux khi Claude xong việc, cần cấp quyền hoặc đặt câu hỏi. Phần này không cần mạng và không cần điện thoại. Mỗi sự kiện nó chỉ chạy vài mili giây; không có gì chạy ngầm cả.

Ghép nối điện thoại iPhone hoặc Android là các sự kiện đó sẽ đến dưới dạng push notification, kể cả trên máy không có desktop. Từ điện thoại, bạn có thể cho phép hoặc từ chối quyền, chọn câu trả lời cho câu hỏi của Claude, và gửi chỉ dẫn tiếp theo khi Claude xong việc. Xem ghép nối điện thoại, trang ccn và bảng giá của app điện thoại. Trên Linux, ccn lưu token trong một file chỉ bạn mới đọc được.

Nếu cài ccn, hãy gỡ các hook notify-send bạn tự thêm để tránh bị thông báo trùng.

09Câu hỏi thường gặp