「Hookを設定したのに、リモートMacで整形やコマンドの制御が動かない」
最初に設定ファイルの適用範囲とイベント・matcherを確認し、その後に実行アカウント、スクリプト環境、戻り値を調べてください。最初からClaude Codeを再インストールする必要はありません。

このガイドは、Hooksを設定したのに処理が見えない開発者、CIでの結果を判断したいDevOps担当者、共有Macの設定範囲を管理するプラットフォーム担当者向けです。

1. 症状を分けて、止まった段階を特定する

Hookが期待どおりに見えない状態は、ひとまとめにしないでください。イベントが発生していない、matcherに一致していない、コマンドが起動していない、起動したが結果が反映されない、という別々の原因が考えられます。

たとえば、コード編集後の整形が動かない場合、まずClaude Codeのセッション記録とHookスクリプトの診断出力を見比べます。ログには秘密情報を出さず、実行したイベント、コマンドの起動有無、終了状態など、切り分けに必要な情報だけを残します。公式のHooks資料にあるデバッグとログの説明も参照してください。

確認は、設定を一度に複数変更せず、ひとつの操作で再現できる状態から始めます。

  1. Claude Codeを起動したアカウントと作業ディレクトリを記録します。
  2. 対象の設定ファイルとHookのイベント名を確認します。
  3. matcherを一時的に単純化し、対象ツールをひとつだけ実行します。
  4. Hookのコマンドが起動したか、標準入力・標準出力・終了状態を確認します。
  5. 条件をひとつずつ元に戻し、失敗する段階を特定します。

2. 読み込まれる設定の範囲を照合する

リモートMacでは、ローカル開発機と同じユーザー設定が使われるとは限りません。SSH接続時のログインアカウント、CIのサービスアカウント、作業ディレクトリが違えば、参照する設定やファイルへのアクセスも変わります。

設定の種類 主な適用範囲 リモートMacでの確認点
ユーザー設定 Claude Codeを実行するユーザー SSHやRunnerのアカウントにも設定があるか
プロジェクト設定 リポジトリに置く設定 実行時の作業ディレクトリが対象リポジトリか
ローカル設定 プロジェクト内の個人用設定 CIや別ユーザーから見える前提になっていないか
管理ポリシー 組織・端末の管理範囲 個人やプロジェクト設定だけで変更できると思い込んでいないか

ファイルの場所と適用範囲は、Claude Codeの公式設定資料で確認してください。どれか一つの設定ファイルだけを見て、他の範囲の設定が有効かどうかまで決めつけないことが重要です。

3. イベントとmatcherを実際の操作に合わせる

設定が存在していても、操作とHookのイベントが対応していなければ実行されません。ツールの実行前後に使うイベントと、セッション終了時に使うイベントは役割が異なります。ファイル変更時の検査を、セッション終了時のHookだけに期待していないか確認してください。

次にmatcherを見ます。対象ツール名や条件が、実際の呼び出しに合っているかを照合します。条件を複数組み合わせている場合は、一時的に一つずつ外して試します。広い条件で動作が確認できたら、必要なmatcherを戻して、どの条件で不一致になるかを特定します。

注意：matcherを広くした状態で本番の操作を続けないでください。原因がわかったら対象を絞り、意図しないコマンドまでHookが制御しないことを確認します。

4. SSHとRunnerの実行環境を比較する

スクリプトが起動しないときは、Hookのロジックより先に、実行ファイルの権限、インタープリターのパス、PATH、依存コマンド、作業ディレクトリ、読み書き権限を確認します。SSHの対話シェルで使えるコマンドでも、Runnerのサービスアカウントで同じように見つかるとは限りません。

たとえば、SSHでは動く整形スクリプトがCIだけで失敗するなら、実行ユーザーとcommand -vの結果、現在のディレクトリ、対象ファイルへのアクセス権を比較します。AppleのSSH経由でXcodeのテスト自動化を行う資料も、接続方法と実行環境を分けて確認する際の参考になります。

ターミナルへのSSH接続が成功しただけでは、HookやXcodeの処理が同じユーザー環境で動いている証明にはなりません。署名情報や認証情報を診断ログに書き出すのも避けてください。

5. 戻り値とブロックの意味を確認する

コマンドが起動しているのに阻止や検査が反映されない場合は、入力と出力の形式、終了コード、イベントごとの決定方法を確認します。Claude CodeのHooks公式資料では、コマンドの終了状態やHook固有の出力によって、処理結果が変わることが説明されています。

たとえば、終了コード0は正常終了、2はブロッキングエラーとして扱われます。JSON出力を使う場合は、標準出力に期待される形式で返しているかも確認してください。診断時には「Hookが一致しなかった」「スクリプトが起動できなかった」「実行したが決定を返さなかった」「後続のツールやCIが失敗した」を別の状態として記録します。

Hookによる操作制御は、OS権限の代替ではありません。権限設定と承認の境界はClaude Codeの権限設定資料で確認し、許可していない操作をHookだけに任せないでください。

6. Xcodeの検証結果とCIの受け入れを分ける

Stop Hookが発火したことと、Xcodeのテストが成功したことは別の事実です。Hookからテストを起動する場合も、テストコマンドの終了状態と結果ファイルを確認し、CIの正式な検証ログとして追跡できるようにします。

Xcodeでテストを実行して結果を解釈する公式資料を参照し、テスト実行の成否を判断してください。コマンドラインから検証する場合は、利用可能なオプションを公式のXcodeコマンドラインツール資料で確かめます。

受け入れ確認では、期待どおりにHookが動くケースだけでなく、意図した条件でブロックされるケース、テストが失敗するケース、Macの再起動後に同じアカウント・環境で再現するケースも記録します。Hookの失敗とXcodeテストの失敗を同じ「CI失敗」にまとめると、次回の調査で原因を取り違えます。

よくある確認事項

リモートMacでClaude Code Hooksが実行されない場合、何から調べますか？

起動アカウント、作業ディレクトリ、読み込まれる設定の順に確認し、その後イベント名とmatcherを一つずつ照合します。最小のツール操作でセッション記録とスクリプトの診断出力を比較すれば、イベント未発生、条件不一致、起動失敗を分けられます。再インストールや設定の全消去は、原因を見えにくくするため最初の手段にしないでください。

リモートMacでClaude Codeが使うHooks設定はどこで決まりますか？

ユーザー、プロジェクト、ローカル、管理ポリシーなどの設定範囲と、Claude Codeを起動したアカウントによって確認対象が変わります。特にCIでは、SSHで使うアカウントや普段の開発ユーザーと異なる場合があります。公式の設定資料でファイルの適用範囲を確かめ、別アカウントに個人設定が自動で引き継がれるとは考えないでください。

PreToolUseのmatcherが対象の操作に一致しない原因は何ですか？

イベント名が対象操作と合っているかを先に見てから、matcherのツール名や条件を照合します。複数の条件を設定している場合は、一度に全部を変更せず、単一イベントと単一ツール呼び出しで試します。matcherを単純化したときだけ動くなら、戻した条件を一つずつ確認すると不一致の要因を絞れます。

SSHでは動くHookがRunnerでコマンドを見つけられないときは？

Runnerの実行アカウントで、PATH、作業ディレクトリ、コマンドの解決結果、実行権限を調べます。ターミナルでのログイン環境とサービスとして動くRunnerの環境は同一とは限りません。秘密情報を除いた診断出力を両方で取り、差がある項目を直してから再実行してください。

Stop Hookの実行だけでXcodeテストの合格を示せますか？

示せません。Stop Hookが動いたことは、テストが起動したことや合格したことを意味しません。テストコマンドの終了状態とXcodeの結果を確認し、CIに記録してください。Hookからテストを実行する構成にしても、正式なビルド・テストの受け入れ工程やOSレベルの権限管理を置き換えるものではありません。

実行環境の差が原因なら、Macの用意方法も見直す

WindowsやLinuxの開発機、一般的なクラウド環境だけでは、macOS固有のツールやXcodeによる検証をそのまま実行できません。手元のMacだけに依存すると、開発者とCIのアカウント・依存関係の差が残り、共有するたびに再現条件をそろえる作業が発生します。一方、自前のMacは継続的に稼働させる用途に向きますが、調達と保守を担う必要があり、物理接続が必須の作業では実機へのアクセス条件も確認が必要です。

環境を一時的にそろえてHooksやXcodeの動作を再現したいなら、MACCOMEのリモートMacを選択肢にできます。必要な期間だけ実環境で検証できる一方、接続品質やアカウント分離、秘密情報の管理は利用側で確認してください。長期にわたる安定した高負荷運用や物理インターフェースが必要なら、自前のMacが適する場合もあります。利用方法はMACCOMEのリモートMac案内で確認でき、購入との比較にはMac miniの案内も参考になります。