GitHub Copilot CLI でフックを使用する

フックを使用すると、エージェントの実行中にキー ポイントでカスタム シェル コマンドを実行することで、 GitHub Copilot エージェントの動作を拡張およびカスタマイズできます。 使用可能なフック トリガーの詳細など、フックの概念の概要については、 フックについて GitHub Copilot を参照してください。

前提条件

Windowsユーザーのみ: この記事のフック例は、Windows、Linux、macOS で実行するように設計されています。 Windowsの場合、PowerShell を使用するため、PowerShell 7.0 以降をインストールして PATH にインストールする必要があります。 ターミナルで pwsh --version を実行することで、PowerShell のバージョンを確認できます。 PowerShell をインストールするには、winget install Microsoft.PowerShell を実行し、ターミナルを再起動します。

リポジトリ レベルのフックの作成

1. リポジトリのNAME.json フォルダーに新しいNAME ファイル (.github/hooks/ファイルの目的を説明するファイル) を作成します。

2. テキスト エディターで、次のフック テンプレートをコピーして貼り付けます。 使用する予定のないフックを hooks 配列から削除します。

   JSON

   {
     "version": 1,
     "hooks": {
       "sessionStart": [...],
       "sessionEnd": [...],
       "userPromptSubmitted": [...],
       "preToolUse": [...],
       "postToolUse": [...],
       "errorOccurred": [...]
     }
   }
   

3. bashキーとpowershell キーでフック構文を構成するか、作成したスクリプト ファイルを直接参照します。

   メモ

   bash キー (Linux および macOS 用のスクリプトを含む) と powershell キー (Windows 用スクリプト用) の両方を含めて、3 つのオペレーティング システムすべてでフックを実行できるようにします。 Copilot は、ユーザーのオペレーティング システムに基づいて適切なキーを使用します。

   • 次の例では、 sessionStart フックを使用してセッションの開始日をログ ファイルに出力するスクリプトを実行します。

     JSON

     "sessionStart": [
       {
         "type": "command",
         "bash": "echo \"Session started: $(date)\" >> logs/session.log",
         "powershell": "Add-Content -Path logs/session.log -Value \"Session started: $(Get-Date)\"",
         "cwd": ".",
         "timeoutSec": 10
       }
     ],
     

   • 次の例では、外部 log-prompt スクリプトを呼び出します。

     JSON

     "userPromptSubmitted": [
       {
         "type": "command",
         "bash": "./scripts/log-prompt.sh",
         "powershell": "./scripts/log-prompt.ps1",
         "cwd": "scripts",
         "env": {
           "LOG_LEVEL": "INFO"
         }
       }
     ],
     

     エージェント セッションからの入力 JSON とサンプル スクリプトの完全なリファレンスについては、 GitHub Copilotフックリファレンス を参照してください。

4. ファイルをリポジトリにコミットし、既定のブランチにマージします。 これで、フックはエージェント セッション中に実行されます。

ユーザー レベルのフックの作成

ユーザー レベルのフックはリポジトリ レベルのフックと同じように構成されますが、フック ファイルはローカルのホーム ディレクトリの下に格納されます。

macOS と Windows の次の例では、CLI がプロンプトに応答し終わったときにサウンドを再生し、メッセージ ボックスを表示するフックを構成し、Copilot CLIを終了する方法を示します。 Linux 用フックは macOS の例に似ていますが、サウンドの再生やメッセージの表示には Linux ツールを使用します。

macOS のユーザー レベルの例

1. notification-hooks.jsonで ~/.copilot/hooks/ という名前のファイルを作成します。

   メモ

   COPILOT_HOMEが設定されている場合は、$COPILOT_HOME/hooks/でファイルを作成します。

2. 次の JSON をコピーしてファイルに貼り付けます。

   JSON

   {
     "version": 1,
     "hooks": {
       "agentStop": [
         {
           "type": "command",
           "bash": "osascript -e 'do shell script \"afplay /System/Library/Sounds/Funk.aiff &> /dev/null &\"' -e 'display dialog \"Agent stopped.\" with title \"Hook-generated message\" buttons {\"OK\"} default button \"OK\"'",
           "timeoutSec": 5
         }
       ],
       "sessionEnd": [
         {
           "type": "command",
           "bash": "osascript -e 'do shell script \"afplay /System/Library/Sounds/Funk.aiff &> /dev/null &\"' -e 'display dialog \"Session ended.\" with title \"Hook-generated message\" buttons {\"OK\"} default button \"OK\"'",
           "timeoutSec": 5
         }
       ]
     }
   }
   

3. Copilot CLIを開始または再起動します。

   メモ

   フック構成の変更は、CLI の開始時に読み込まれます。

4. プロンプトを入力し、エージェントの応答が終了したとき、および CLI を終了したときに、音声が聞こえてメッセージ ボックスが表示されることを確認します。

5. これらのフックを削除するには、 notification-hooks.json ファイルを削除します。

Windowsのユーザー レベルの例

1. notification-hooks.jsonで %USERPROFILE%\.copilot\hooks\ という名前のファイルを作成します。

   メモ

   COPILOT_HOMEが設定されている場合は、%COPILOT_HOME%\hooks\でファイルを作成します。

2. 次の JSON をコピーしてファイルに貼り付けます。

   JSON

   {
     "version": 1,
     "hooks": {
       "agentStop": [
         {
           "type": "command",
           "powershell": "Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Agent stopped.', 'Hook-generated message') | Out-Null",
           "timeoutSec": 5
         }
       ],
       "sessionEnd": [
         {
           "type": "command",
           "powershell": "Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Session ended.', 'Hook-generated message') | Out-Null",
           "timeoutSec": 5
         }
       ]
     }
   }
   

3. Copilot CLIを開始または再起動します。

   メモ

   フック構成の変更は、CLI の開始時に読み込まれます。

4. プロンプトを入力し、エージェントの応答が終了したとき、および CLI を終了したときに、音声が聞こえてメッセージ ボックスが表示されることを確認します。

5. これらのフックを削除するには、 notification-hooks.json ファイルを削除します。

トラブルシューティング

フックを使用して問題が発生した場合は、次の表を使用してトラブルシューティングを行います。

問題点	アクション
フックが実行されていない	JSON ファイルが .github/hooks/ ディレクトリ内にあるかどうかを確認します。 有効な JSON 構文 (たとえば、 jq . hooks.json) を確認します。
version: 1 ファイルにhooks.jsonが指定されていることを確認します。 フックから呼び出しているスクリプトが実行可能であることを確認します (chmod +x script.sh) スクリプトに適切な shebang があることを確認します (例: #!/bin/bash)
フックがタイムアウトする	既定のタイムアウトは 30 秒です。 必要に応じて、構成の timeoutSec を増やします。 不要な操作を回避してスクリプトのパフォーマンスを最適化します。
無効な JSON 出力	出力が 1 行であることを確認します。 Unix では、 jq -c を使用して JSON 出力を圧縮して検証します。 Windowsで、PowerShell の ConvertTo-Json -Compress コマンドを使用して同じ操作を行います。

デバッグ

次のメソッドを使用してフックをデバッグできます。

• スクリプトで詳細ログを有効化して、入力データを検査し、スクリプトの実行を追跡します。

  Shell

  #!/bin/bash
  set -x  # Enable bash debug mode
  INPUT=$(cat)
  echo "DEBUG: Received input" >&2
  echo "$INPUT" >&2
  # ... rest of script
  

• テストフックをローカルでテストするために、テスト入力をフックにパイプし、その動作を検証します。

  Shell

  # Create test input
  echo '{"timestamp":1704614400000,"cwd":"/tmp","toolName":"bash","toolArgs":"{\"command\":\"ls\"}"}' | ./my-hook.sh
  
  # Check exit code
  echo $?
  
  # Validate output is valid JSON
  ./my-hook.sh | jq .
  

詳細については、次を参照してください。

• GitHub Copilotフックリファレンス
• クラウド エージェントGitHub Copilotについて
• GITHUB COPILOT CLI について
• 開発環境を構成する