CodexのHooksを理解する

Hooksは、Codexの処理の決まったタイミングでスクリプトなどを動かす仕組みです。「作業開始時に短い注意を渡したい」など、同じ処理を毎回実行したい場合に検討できます。この記事は、設定をいきなり有効化せず、仕組みと確認順を理解するための入門です。

イベント・条件・処理の三つに分ける

公式資料では、設定は hooks.json または config.toml のHook定義に置けます。プロジェクト用の .codex/ とユーザー用の場所があり、複数の定義があれば一致するHookが読み込まれます。普通の設定のように上位の一つだけへ置き換わると思わないことが大切です。Hooksの公式説明

各段階で確認してから、次の操作へ進みます。

1. 1タイミング開始時などのイベントを決めます。
2. 2条件と処理何に一致し、何を実行するか確認します。
3. 3単体から試すコマンドを先に確認し、その後Hookを検証します。

具体的な依頼と、結果の確かめ方は本文にあります。

単体のプログラムが動くことと、Codexがイベントに応じて呼び出せることを順番に確かめます。

最初は設定せず処理だけ試す

Node.jsを利用できる練習フォルダーに session-note.mjs を作る例です。既存のファイルへ上書きせず、次の一行を保存します。

console.log('開始前に、対象ファイルと完了条件を確認してください。');

PowerShellから実行します。

node ./session-note.mjs

表示されるのは短い注意文だけです。この例はファイルを変更したり外部へ送信したりしません。ファイル名が違う場合は、まず単体実行のエラーを直します。

設定例は場所を置き換えてから使う

以下は構造を示す例です。C:/codex-practice/session-note.mjs は自分で作ったファイルの実際の絶対パスへ置き換えます。Node.jsもCodexの実行環境から利用できる必要があります。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "node C:/codex-practice/session-note.mjs",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

空白を含むパスではコマンド側の引用符とJSONのエスケープが必要です。最初は空白のない専用パスで試すと、仕組みと引用符の問題を切り分けられます。既存の hooks.json がある場合、ファイル全体をこの例へ置き換えないでください。

CLIでは /hooks から定義を確認できます。管理対象外の新規・変更Hookは内容をレビューして信頼するまで実行されません。プロジェクトの信頼状態も読み込みに関係します。自分で内容と参照先を確認し、必要な範囲で試してください。

成功の確認と戻し方

1. 単体実行で意図した文だけが出るか確認します。
2. Codexが読み込む設定場所と、表示されるHookの参照先を確認します。
3. 新しいセッションで、開始時の文が反映されたか確認します。
4. 二重に出る場合はユーザー用・プロジェクト用・プラグインの重複定義を調べます。
5. 不要になった場合は、今回追加した管理対象外Hookを無効にし、次のセッションで確認します。

この記事ではJavaScriptの単体実行とJSON構文を検査しました。Codexへの登録・信頼操作・イベント発火は未検証です。単体検査の成功を、Hookの導入完了とは扱いません。

Skillsや定期実行との違い

毎回使う手順をまとめるならSkills、決まった時刻に始めるなら定期点検を検討します。Hooksを使う理由が「何となく自動化したい」だけなら、まず手動で必要な確認を整理すると、実行する処理を小さく決められます。