ガイド
Claude Code のフックを解説:その仕組みと作れるもの
結論: フックを使うと、ツールの開始時、権限の要求時、ターン終了時に Claude Code があなたのコマンドを実行します。その仕組みと、Herdbell がどう使っているかを解説します。
フックとは、エージェントが決まったタイミングで実行する小さなコマンドです。Claude Code、Codex、Cursor はいずれも何らかの形で対応しており、サインインや画面スクレイピングなしで、別のプログラムがエージェントの動きを追うための確実な方法です。
考え方を一段落で
エージェントに「これが起きたら、このコマンドを実行して」と伝えます。エージェントはそれを実行し、イベントの短い説明を渡します。コマンドは記録するだけ(通知を送るなど)にもできますし、一部のイベントでは、エージェントが使う答えを返すこともできます。
フックできるタイミング
正確なイベント名や設定はエージェントやバージョンによって異なります。自作する前に、各エージェントのドキュメントを確認してください。
- セッションの開始・終了、またはプロンプトの送信があったとき。
- ツールがこれから実行される、または実行されたとき。
- エージェントが何かをするための権限を求める。
- エージェントがターンを終了する(Stop イベント)。
置き場所
設定ファイルです。Claude Code は ~/.claude/settings.json、Codex は ~/.codex/hooks.json、Cursor は ~/.cursor/hooks.json です。これらのファイルを手で編集しても問題なく、Herdbell のようなツールが接続する方法でもあります。
Herdbell がフックを使う方法
- 接続時に Herdbell はファイルをバックアップしてから、必要なイベント用の自身の小さなコマンドを追加します。
- ほとんどのイベントでは聞いているだけなので、エージェントの動きを表示できます。
- 権限リクエストでは、あなたの答えを待って返すので、Allow と Deny がそのまま反映されます。ターンの終了では、エージェントを待機させておけるため、あなたの返信が同じチャットに戻ります。
- 時間内に答えなければ手を引き、エージェントは自身のプロンプトに戻ります。接続を解除すると、Herdbell のフックだけが削除されます。
よくある質問
フックには API キーやログインが必要ですか?
いいえ。フックは Mac 上のローカルなコマンドです。Herdbell はフックを使うことで、エージェントにサインインしたり AI モデルを呼び出したりせずに済みます。
フックでエージェントが壊れることはありますか?
出来の悪いものは動作を遅くしたり混乱させたりすることがあります。そのため Herdbell は先に設定をバックアップし、フックを小さく保ち、答えがないときは手を引きます。いつでも切断できます。