Claude Code の hooks 入門：Linux/SSH 環境で“承認待ち・完了”を通知する設定【動作確認済み】

Claude Code に作業を任せて別のことをしていると、「承認待ちで止まっていた」「とっくに終わっていた」ということがよくあります。hooks を使うと、こうしたタイミングで決まったコマンドを自動で実行できるので、通知を飛ばしたり、編集後に自動でフォーマットしたりできます。

日本語の解説記事は macOS（osascript や terminal-notifier）前提のものが多いので、この記事では GUI のない Linux サーバー（SSH でつないで使う想定） で、実際に設定して動作を確かめた手順をまとめます。

検証環境

Claude Code は更新が速く、hooks の仕様もバージョンごとに変わっています。この記事の内容は上記バージョンで確認したものです。

hooks とは

hooks は、Claude Code の決まったタイミング（イベント）で自動的に実行されるシェルコマンドです。Claude（モデル）が「実行するかどうか」を判断するのではなく、条件に合えば必ず実行されるのがポイントです。

イベントはたくさんありますが、この記事で使うのは次の 4 つです。

設定ファイルの置き場所

hooks は settings.json の hooks キーに書きます。どのファイルに書くかで、効く範囲が変わります（公式ガイドより）。

ほかに、組織の管理設定・プラグイン・スキルやサブエージェントの frontmatter にも書けます。

今回は次のように分けました。

• 通知（Notification / Stop） … どのプロジェクトでも欲しいので ~/.claude/settings.json
• 整形とブロック（PostToolUse / PreToolUse） … プロジェクトごとのルールなので .claude/settings.json

手順 1：通知用スクリプトを作る

まず、Notification と Stop の両方から呼ぶスクリプトを ~/.claude/hooks/notify.sh に作ります。やっていることは次の 3 つです。

1. 標準入力の JSON から、イベント名とメッセージを取り出す
2. GUI のセッションがあれば notify-send でデスクトップ通知（失敗しても止めない）
3. ntfy のトピック名が設定されていれば、curl でスマホに通知

#!/usr/bin/env bash
# Claude Code の Notification / Stop フックから呼ぶ通知スクリプト
# stdin でフックの JSON を受け取る
INPUT=$(cat)
EVENT=$(printf '%s' "$INPUT" | jq -r '.hook_event_name // "unknown"')
case "$EVENT" in
  Notification) MSG=$(printf '%s' "$INPUT" | jq -r '.message // "入力待ちです"') ;;
  Stop)         MSG="応答が完了しました" ;;
  *)            MSG="$EVENT" ;;
esac
PROJECT=$(basename "$(printf '%s' "$INPUT" | jq -r '.cwd // "."')")
LOG="$HOME/.claude/hooks/notify.log"
echo "$(date '+%F %T') $EVENT [$PROJECT] $MSG" >> "$LOG"

# 1) デスクトップ通知（GUI セッションがあるときだけ。失敗しても止めない）
if command -v notify-send >/dev/null 2>&1 && [ -n "$DBUS_SESSION_BUS_ADDRESS$DISPLAY$WAYLAND_DISPLAY" ]; then
  notify-send "Claude Code ($PROJECT)" "$MSG" >>"$LOG" 2>&1 || echo "notify-send failed" >> "$LOG"
fi

# 2) スマホ通知（ntfy）。トピック名は環境変数かファイルから読む
TOPIC="${NTFY_TOPIC:-$(cat "$HOME/.config/claude-ntfy-topic" 2>/dev/null)}"
if [ -n "$TOPIC" ]; then
  curl -sS -o /dev/null -w "ntfy HTTP %{http_code}\n" --max-time 10 \
    -H "Title: Claude Code ($PROJECT)" -d "$MSG" "https://ntfy.sh/$TOPIC" >> "$LOG" 2>&1
fi
exit 0

mkdir -p ~/.claude/hooks
chmod +x ~/.claude/hooks/notify.sh

Stop のメッセージを固定文にしているのは、ntfy.sh の公開サーバーにコードや会話の内容を送らないためです（理由は手順 4 で説明します）。

手順 2：Notification と Stop を登録する

~/.claude/settings.json に次のように書きます（ファイルがなければ作ります）。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/notify.sh" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/notify.sh" }
        ]
      }
    ]
  }
}

• matcher が空だと、すべての通知タイプで発火します。承認待ちだけにしたいなら "permission_prompt"、約 60 秒入力がないときだけなら "idle_prompt" にします。
• Stop は matcher に対応していないので書きません。

保存したら JSON として正しいかを確認しておきます。何も表示されなければ OK です。

jq empty ~/.claude/settings.json

手順 3：notify-send はヘッドレス環境で使えるか

公式ガイドの Linux 向けの例は notify-send です。GUI のない環境で試すとどうなるかを確認しました。

まず、notify-send 自体が入っていませんでした。

$ notify-send 'Claude Code' 'test'
notify-send: command not found
$ echo $?
127

Debian/Ubuntu では libnotify-bin パッケージに入っています。今回の環境では、最初の apt-get install が E: Unable to locate package libnotify-bin で失敗し、apt-get update してから入れ直す必要がありました。

sudo apt-get update
sudo apt-get install -y libnotify-bin

インストール後に実行すると、次のようになりました。

つまり、SSH 先のサーバーやコンテナでは、notify-send を入れても通知は届きません。手元の PC に通知を出す仕組みではないためです。そこで、スマホや別の PC に届く ntfy を使います。

上のスクリプトは notify-send が失敗しても終了コード 0 で終わるので、Claude Code の動作には影響しません。デスクトップ環境のある Linux で使う場合はそのまま通知が出るはずですが、今回は未確認です。

手順 4：ntfy でスマホに通知する

ntfy は、URL に HTTP で POST するだけでスマホに通知を送れるサービスです。アカウント登録なしで、公開サーバー ntfy.sh を使えます。

トピック名を決める

ntfy の公式ドキュメントにも「トピック名は公開されているので、推測されにくい名前にする」とあります。トピック名を知っている人は誰でも通知を読めるので、ランダムな文字列にします。

TOPIC="cc-hooks-$(head -c 9 /dev/urandom | od -An -tx1 | tr -d ' \n')"
echo "$TOPIC"                           # スマホのアプリに登録するので控えておく
mkdir -p ~/.config
echo "$TOPIC" > ~/.config/claude-ntfy-topic

curl で送れるか試す

curl -sS -w '\nHTTP %{http_code}\n' -H 'Title: Claude Code' -d 'manual test from box' "https://ntfy.sh/$TOPIC"

スマホがなくても、届いたメッセージは次のコマンドで確認できます。最初 ?poll=1 だけで試したら何も返ってこず、since=all を付けると表示されました。

curl -sS "https://ntfy.sh/$TOPIC/json?poll=1&since=all"

スマホ側の設定

ntfy の公式アプリ（Android / iOS）を入れ、「＋」から同じトピック名を登録すれば、以後の通知がスマホに届きます。ブラウザで https://ntfy.sh/トピック名 を開いても一覧を見られます。この記事の検証で、実際にフックから届いた通知の一覧です。

手順 5：通知が届くか確かめる

完了通知（Stop）

claude -p（非対話モード）で 1 回だけ指示を出し、終わったときに Stop が動くかを見ました。応答が終わった直後、notify.sh のログにこう記録されました。

2026-10-19 12:56:54 Stop [hooks-demo] 応答が完了しました
GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown: The name org.freedesktop.Notifications was not provided by any .service files
notify-send failed
ntfy HTTP 200

デスクトップ通知は失敗、ntfy は成功、という想定どおりの結果です。

承認待ち通知（Notification）

承認待ちの通知を試すには、Claude Code が承認を求める状況を作る必要があります。ここで 1 つ注意点がありました。

2.1.303 では、起動直後の権限モードが auto mode でした。 auto mode では Claude Code が多くの承認を自動で処理するため、承認待ちの状況を作りにくくなります。

テストでは Shift+Tab を何回か押し、画面下に ⏸ manual mode on と出る状態にしました（押すたびに manual → accept edits → plan → auto と切り替わりました）。

manual mode でも、date のような読み取りだけのコマンドは確認なしで実行されました。touch note.txt を頼むと、承認画面が出ました。

2026-10-19 12:59:44 Notification [hooks-demo] Claude needs your permission
...
ntfy HTTP 200

idle_prompt（応答後に約 60 秒入力がない）は今回は試していません。

手順 6：/hooks で設定を確認する

対話モードで /hooks と入力すると、登録済みのフックが一覧で表示されます。

項目を選んで Enter を押すと、読み込み元のファイルも表示されます。

手順 7：編集後に自動整形する（PostToolUse）

Claude がファイルを書いたり編集したりした直後に、Prettier をかけます。プロジェクトに Prettier を入れておきます。

npm i -D prettier

プロジェクトの .claude/settings.json に書きます（PreToolUse と同じファイルにまとめた最終形は手順 8 にあります）。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write --ignore-unknown"
          }
        ]
      }
    ]
  }
}

確認

Claude に「シングルクォートで 1 行に詰めた hello.js を Write ツールで作って」と頼みました。manual mode なので、書き込む前に承認画面が出ます。ここに表示されているのが、Claude が書こうとした内容（整形前）です。

承認すると書き込まれ、その直後に PostToolUse フックが動きます。Claude 自身も「PostToolUse フックがファイルを変更した」ことに気づいていました。

実際のファイルを見ると、整形されていました。

claude -p に --output-format stream-json --verbose --include-hook-events を付けて実行すると、フックの実行結果も出力に含まれます。今回は次のように記録されていました（ID などのフィールドは省略しています）。

{"type":"system","subtype":"hook_response","hook_name":"PostToolUse:Write","hook_event":"PostToolUse","output":"hello.js 31ms\n","stdout":"hello.js 31ms\n","stderr":"","exit_code":0,"outcome":"success"}

注意点として、Edit|Write の matcher は Claude が Bash でファイルを書き換えた場合には発火しません。公式ガイドでは、その場合も含めて整形したいなら FileChanged フックを使うよう案内されています（今回は未検証）。

手順 8：危険なコマンドをブロックする（PreToolUse）

PreToolUse はツールの実行前に動き、終了コード 2 で終わるとその実行をブロックできます。このとき標準エラー出力（stderr）に書いた内容が、理由として Claude に伝わります。

.claude/hooks/block-dangerous.sh を作ります。

#!/usr/bin/env bash
# PreToolUse(Bash) で危険なコマンドを止める
CMD=$(jq -r '.tool_input.command // empty')
if printf '%s' "$CMD" | grep -Eq 'rm[[:space:]]+(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r)'; then
  echo "Blocked by hook: 'rm -rf' は禁止です。削除が必要ならユーザーに確認してください。" >&2
  exit 2
fi
exit 0

chmod +x .claude/hooks/block-dangerous.sh

Claude Code に登録する前に、JSON をパイプで渡して単体で試しておくと安心です。

プロジェクトの .claude/settings.json（PostToolUse と合わせた最終形）です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write --ignore-unknown" }
        ]
      }
    ]
  }
}

確認

tmpdir/ を作っておき、Claude に rm -rf ./tmpdir を実行するよう頼みました。通常の画面では「Ran 1 shell command」と短く表示されるだけなので、Ctrl+O で詳細表示に切り替えています。

手順 9：フック自体が壊れていたら？（onFailure）

ブロック用のフックで、スクリプトのパスを打ち間違えていたらどうなるでしょうか。わざと存在しないスクリプト policy-check.sh を指定して試しました。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/policy-check.sh",
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

onFailure は v2.1.295 で追加された項目で、command と http のフックに指定できます。値は "continue"（既定）か "block" です（hooks リファレンス）。echo hello-from-bash を実行させた結果はこうでした。

つまり onFailure を付けないと、ガード用のフックが壊れていても素通りになります。ブロック目的のフックには "onFailure": "block" を付けておくと安心です。

リファレンスによると、Stop などの一部のイベントや、async で動かすフックには onFailure は効きません。また、0 と 2 以外の終了コードやタイムアウトも「失敗」として扱われます（タイムアウトは今回未検証）。

うまく動かないときのチェックリスト

今回の検証で実際に出たエラーと、その対処です。

• notify-send: command not found（終了コード 127） → libnotify-bin を入れる。Unable to locate package なら先に sudo apt-get update。
• Cannot autolaunch D-Bus without X11 $DISPLAY → SSH・ヘッドレス環境です。notify-send では通知できないので ntfy などを使う。
• The name org.freedesktop.Notifications was not provided by any .service files → 通知デーモンが動いていません。サーバーでは ntfy などを使う。
• settings.json の JSON が壊れている → 起動時なら「Settings Error … Invalid or malformed JSON」「Files with errors are skipped entirely, not just the invalid settings.」という画面が出ます。セッション中に壊した場合は画面に警告が出ず、そのファイルのフックが /hooks から消えるだけでした。claude doctor か jq empty で確認できます（末尾のカンマが典型例です）。なお claude --help によると、-p モードでは検証に失敗した設定ファイルはエラー表示なしで無視されます（この挙動は未検証）。
• スクリプトが見つからない（not found、終了コード 127） → パスの打ち間違い。onFailure がないとエラーが出ても処理は続行されます。
• スクリプトに実行権限がない（Permission denied、終了コード 126） → chmod +x する。今回は sh -c で同じ呼び出し方を再現して確認しました。
• Prettier の No parser could be inferred → --ignore-unknown を付ける。
• 承認待ちの通知が来ない → auto mode だと承認画面自体が出にくい。テスト時は Shift+Tab で manual mode にし、ファイルを変更するコマンドを頼む。
• ntfy の poll で何も返ってこない → ?poll=1&since=all にする。

JSON をわざと壊して（末尾にカンマを入れて）確認したときの画面です。

フックの動きを詳しく見る方法

• claude --debug-file /tmp/claude.log で起動すると、Hooks: PreToolUse:Bash [...] finished with status 2 (17ms) のように、フックごとの終了コードと実行時間が記録されます。
• claude -p "..." --output-format stream-json --verbose --include-hook-events なら、hook_response に終了コード・stdout・stderr が入ります。
• 対話モードでは Ctrl+O で詳細表示に切り替えると、フックのエラー全文が見えます。

なお、デバッグログの時刻は UTC（末尾が Z）で記録されていました。日本時間に直すには 9 時間足します。

まとめ

hooks は「必ず実行したい処理」に向いた仕組みです。決まった手順を Claude に任せたいなら Skills（SKILL.md）、外部のツールやデータにつなぎたいなら MCP も組み合わせられます。429 や 529 で止まったときの見分け方は エラー・利用制限のまとめ にまとめました。

参考

• hooks でアクションを自動化する（公式ガイド）
• Hooks リファレンス（公式）
• ntfy ドキュメント

この記事は、AI を使って下書きを作り、手順とコマンドの出力・画面は筆者の検証環境で実際に実行して確認しています。アイキャッチ画像は生成画像（イラスト）で、実際の画面ではありません。