# GitHub Copilot CLI でフックを使用する エージェントの実行中 GitHub Copilot キー ポイントでカスタム シェル コマンドを使用して、エージェントの動作を拡張します。 フックを使用すると、エージェントの実行中にキー ポイントでカスタム シェル コマンドを実行することで、 GitHub Copilot エージェントの動作を拡張およびカスタマイズできます。 使用可能なフック トリガーの詳細など、フックの概念の概要については、 [フックについて GitHub Copilot](/ja/copilot/concepts/agents/hooks) を参照してください。 ## 前提条件 **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 copy { "version": 1, "hooks": { "sessionStart": [...], "sessionEnd": [...], "userPromptSubmitted": [...], "preToolUse": [...], "postToolUse": [...], "errorOccurred": [...] } } ``` 3. `bash`キーと`powershell` キーでフック構文を構成するか、作成したスクリプト ファイルを直接参照します。 > \[!NOTE] > `bash` キー (Linux および macOS 用のスクリプトを含む) と `powershell` キー (Windows 用スクリプト用) の両方を含めて、3 つのオペレーティング システムすべてでフックを実行できるようにします。 Copilot は、ユーザーのオペレーティング システムに基づいて適切なキーを使用します。 * 次の例では、 `sessionStart` フックを使用してセッションの開始日をログ ファイルに出力するスクリプトを実行します。 ```json copy "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 copy "userPromptSubmitted": [ { "type": "command", "bash": "./scripts/log-prompt.sh", "powershell": "./scripts/log-prompt.ps1", "cwd": "scripts", "env": { "LOG_LEVEL": "INFO" } } ], ``` エージェント セッションからの入力 JSON とサンプル スクリプトの完全なリファレンスについては、 [GitHub Copilotフックリファレンス](/ja/copilot/reference/hooks-reference) を参照してください。 4. ファイルをリポジトリにコミットし、既定のブランチにマージします。 これで、フックはエージェント セッション中に実行されます。 ## ユーザー レベルのフックの作成 ユーザー レベルのフックはリポジトリ レベルのフックと同じように構成されますが、フック ファイルはローカルのホーム ディレクトリの下に格納されます。 macOS と Windows の次の例では、CLI がプロンプトに応答し終わったときにサウンドを再生し、メッセージ ボックスを表示するフックを構成し、Copilot CLIを終了する方法を示します。 Linux 用フックは macOS の例に似ていますが、サウンドの再生やメッセージの表示には Linux ツールを使用します。 ### macOS のユーザー レベルの例 1. `notification-hooks.json`で `~/.copilot/hooks/` という名前のファイルを作成します。 > \[!NOTE] > `COPILOT_HOME`が設定されている場合は、`$COPILOT_HOME/hooks/`でファイルを作成します。 2. 次の JSON をコピーしてファイルに貼り付けます。 ```json copy { "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を開始または再起動します。 > \[!NOTE] > フック構成の変更は、CLI の開始時に読み込まれます。 4. プロンプトを入力し、エージェントの応答が終了したとき、および CLI を終了したときに、音声が聞こえてメッセージ ボックスが表示されることを確認します。 5. これらのフックを削除するには、 `notification-hooks.json` ファイルを削除します。 ### Windowsのユーザー レベルの例 1. `notification-hooks.json`で `%USERPROFILE%\.copilot\hooks\` という名前のファイルを作成します。 > \[!NOTE] > `COPILOT_HOME`が設定されている場合は、`%COPILOT_HOME%\hooks\`でファイルを作成します。 2. 次の JSON をコピーしてファイルに貼り付けます。 ```json copy { "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を開始または再起動します。 > \[!NOTE] > フック構成の変更は、CLI の開始時に読み込まれます。 4. プロンプトを入力し、エージェントの応答が終了したとき、および CLI を終了したときに、音声が聞こえてメッセージ ボックスが表示されることを確認します。 5. これらのフックを削除するには、 `notification-hooks.json` ファイルを削除します。 ## トラブルシューティング フックを使用して問題が発生した場合は、次の表を使用してトラブルシューティングを行います。 | 問題点 | アクション | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | フックが実行されていない | | | | フックがタイムアウトする | | | 無効な JSON 出力 | | ## デバッグ 次のメソッドを使用してフックをデバッグできます。 * スクリプトで**詳細ログを有効化**して、入力データを検査し、スクリプトの実行を追跡します。 ```shell copy #!/bin/bash set -x # Enable bash debug mode INPUT=$(cat) echo "DEBUG: Received input" >&2 echo "$INPUT" >&2 # ... rest of script ``` * **テストフックをローカルでテストするために、テスト入力をフックにパイプし**、その動作を検証します。 ```shell copy # 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フックリファレンス](/ja/copilot/reference/hooks-reference) * [クラウド エージェントGitHub Copilotについて](/ja/copilot/concepts/agents/cloud-agent/about-cloud-agent) * [GITHUB COPILOT CLI について](/ja/copilot/concepts/agents/copilot-cli/about-copilot-cli) * [開発環境を構成する](/ja/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment)