Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

フックのJSON出力にterminalSequenceフィールドを追加しました。制御端末がない環境でも、フックからデスクトップ通知・ウィンドウタイトル変更・ベル（通知音）を発行できます。

原文（英語） ​

Added terminalSequence field to hook JSON output so hooks can emit desktop notifications, window titles, and bells without a controlling terminal

概要 ​

Claude Codeのフックシステムは、ツール呼び出しやセッションイベントをトリガーにシェルスクリプトを実行できます。これまで端末シーケンス（OSCエスケープシーケンスなど）は制御端末がある場合にのみ機能していましたが、terminalSequenceフィールドの追加により、tmuxやバックグラウンドプロセスなどの環境でもデスクトップ通知や音声アラートを確実に届けられるようになりました。

基本的な使い方 ​

フックスクリプトのJSON出力にterminalSequenceフィールドを含めるだけです。Claude Codeがそのシーケンスを適切に端末へ転送します。

json
{
  "terminalSequence": ""
}

上記はベル文字（BEL、\a）を送出する最もシンプルな例です。Claude Codeが処理を完了したときに音で通知します。

実践例 ​

ウィンドウタイトルを変更して進捗を表示する ​

bash
#!/bin/bash
# PostToolUse フックに設定する例
# ツール名をウィンドウタイトルに表示する

TOOL_NAME="${CLAUDE_TOOL_NAME:-unknown}"
OSC_TITLE="\033]0;Claude: ${TOOL_NAME} 完了\007"

echo "{\"terminalSequence\": \"$(printf '%s' "$OSC_TITLE" | sed 's/\\/\\\\/g; s/"/\\"/g')\"}"

macOSでデスクトップ通知を送る（tmux対応） ​

tmux内からでもOSCシーケンスを使ってデスクトップ通知を送れます。

bash
#!/bin/bash
# ~/.claude/hooks/stop-notification.sh
# StopHook: Claude がターンを完了したときに通知

MESSAGE="Claude Code がタスクを完了しました"

# macOS 通知センター経由で通知（Appleescript）
osascript -e "display notification \"${MESSAGE}\" with title \"Claude Code\""

# terminalSequence で端末ベルも鳴らす
echo '{"terminalSequence": ""}'

settings.jsonへのフック登録:

json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/stop-notification.sh"
          }
        ]
      }
    ]
  }
}

Windowsでトースト通知を送る ​

powershell
# stop-notification.ps1
$title = "Claude Code"
$message = "タスクが完了しました"

[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null
$template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent(
    [Windows.UI.Notifications.ToastTemplateType]::ToastText02
)
$template.SelectSingleNode('//text[@id="1"]').InnerText = $title
$template.SelectSingleNode('//text[@id="2"]').InnerText = $message
$toast = [Windows.UI.Notifications.ToastNotification]::new($template)
[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("Claude Code").Show($toast)

# terminalSequence でベルを鳴らす
Write-Output '{"terminalSequence": ""}'

ターミナルタブのタイトルを更新する（Kitty / WezTerm） ​

bash
#!/bin/bash
# PreToolUse フック: ツール実行前にタブタイトルを更新

TOOL="${CLAUDE_TOOL_NAME:-thinking}"

# OSC 0: ウィンドウタイトルとアイコン名を同時に設定
SEQUENCE="\033]0;[Claude] ${TOOL}\007"

echo "{\"terminalSequence\": \"\\033]0;[Claude] ${TOOL}\\007\"}"

注意点 ​

  • terminalSequenceの値は文字列で、端末に直接書き込まれます。OSCエスケープシーケンスを正しくエスケープしてJSON文字列として出力してください。
  • tmux環境では、tmux自体がOSCシーケンスを遮断する設定になっている場合があります。tmuxのset -g allow-passthrough on設定が必要なケースがあります。
  • フックのJSON出力にterminalSequence以外のフィールドを含めることもできます（stopReasonなど）。
  • バックグラウンドエージェント（/bgや←←で起動したもの）では制御端末がないため、このフィールドが特に有効です。

関連情報 ​