GitHub Copilot CLI（コマンドラインインターフェース）でフックを使用する

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

前提条件

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

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

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

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

JSON

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

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

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
  }
],

"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"
    }
  }
],

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

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

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

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

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

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

macOS のユーザーレベルの例

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

メモ

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

次の 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
      }
    ]
  }
}

{
  "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
      }
    ]
  }
}

Copilot CLI (コパイロット CLI)を開始または再起動します。

メモ

フック構成の変更は、CLI の開始時に読み込まれます。
プロンプトを入力し、エージェントの応答が終了したとき、および CLI を終了したときに、音声が聞こえてメッセージボックスが表示されることを確認します。
これらのフックを削除するには、 notification-hooks.json ファイルを削除します。

Windowsのユーザーレベルの例

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

メモ

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

次の 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
      }
    ]
  }
}

{
  "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
      }
    ]
  }
}

Copilot CLI (コパイロット CLI)を開始または再起動します。

メモ

フック構成の変更は、CLI の開始時に読み込まれます。
プロンプトを入力し、エージェントの応答が終了したとき、および CLI を終了したときに、音声が聞こえてメッセージボックスが表示されることを確認します。
これらのフックを削除するには、 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

#!/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 .

# 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 CLI（コマンドラインインターフェース）でフックを使用する

この記事で

前提条件

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

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

macOS のユーザーレベルの例

Windowsのユーザーレベルの例

トラブルシューティング

デバッグ

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

GitHub Copilot CLI（コマンドラインインターフェース） でフックを使用する

この記事で

GitHub Copilot CLI（コマンドラインインターフェース）でフックを使用する