GitHub Copilot 명령 줄 인터페이스 (CLI)로 후크 사용하기

후크를 사용하면 에이전트를 실행하는 동안 키 지점에서 사용자 지정 셸 명령을 실행하여 에이전트의 GitHub Copilot 동작을 확장하고 사용자 지정할 수 있습니다. 사용 가능한 후크 트리거의 세부 정보를 포함하여 후크의 개념적 개요는 후크에 대한 정보 GitHub Copilot을 참조하세요.

전제 조건

          **만 Windows 경우:** 이 문서의 예제에서는 PowerShell을 사용합니다. Windows 사용하는 경우 PowerShell 7.0 이상이 설치되어 있어야 하며 PATH에 있어야 합니다. 터미널에서 실행 `pwsh --version` 하여 PowerShell 버전을 확인할 수 있습니다. PowerShell을 설치하려면 `winget install Microsoft.PowerShell` 실행한 다음 터미널을 다시 시작합니다.

리포지토리 수준 후크 만들기

리포지토리의 .github/hooks/ 폴더에 새 NAME.json 파일(NAME는 파일의 용도를 설명함)을 만듭니다.

텍스트 편집기에서 다음 후크 템플릿을 복사하여 붙여넣습니다. 사용하지 않을 계획인 후크를 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 스크립트용)를 모두 포함합니다. 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가 프롬프트에 응답하는 것을 완료하고 코파일럿 CLI 종료할 때 소리를 재생하고 메시지 상자를 표시하는 후크를 구성하는 방법을 보여 줍니다. Linux용 후크는 macOS 예제와 유사하지만, 소리를 재생하고 메시지를 표시하기 위해 Linux 도구를 사용합니다.

macOS에 대한 사용자 수준 예제

       `~/.copilot/hooks/`에 `notification-hooks.json`이라는 파일을 만듭니다.

참고

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

```
       코파일럿 CLI을(를) 시작하거나 다시 시작합니다.
```
참고

후크 구성에 대한 변경 내용은 CLI가 시작될 때 로드됩니다.
프롬프트를 입력하고 소리가 들리고 에이전트가 응답을 완료하고 CLI를 종료할 때 메시지 상자가 표시되는지 확인합니다.

       `notification-hooks.json` 파일을 삭제하여 이러한 후크를 제거합니다.

Windows 대한 사용자 수준 예제

       `%USERPROFILE%\.copilot\hooks\`에 `notification-hooks.json`라는 파일을 만듭니다.

참고

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

```
       코파일럿 CLI을(를) 시작하거나 다시 시작합니다.
```
참고

후크 구성에 대한 변경 내용은 CLI가 시작될 때 로드됩니다.
프롬프트를 입력하고 소리가 들리고 에이전트가 응답을 완료하고 CLI를 종료할 때 메시지 상자가 표시되는지 확인합니다.

       `notification-hooks.json` 파일을 삭제하여 이러한 후크를 제거합니다.

문제 해결

후크를 사용하여 문제가 발생하면 다음 표를 사용하여 문제를 해결합니다.

Issue	조치
후크가 실행되고 있지 않습니다.	JSON 파일이 디렉터리에 있는지 `.github/hooks/` 확인합니다. 유효한 JSON 구문(예: `jq . hooks.json`)을 확인합니다.

          `version: 1`이 당신의 `hooks.json` 파일에 지정되어 있는지 확인하십시오.</li><li>후크에서 호출하는 스크립트가 실행 파일인지 확인(`chmod +x script.sh`)</li><li>스크립트에 적절한 shebang이 있는지 확인합니다(예: `#!/bin/bash`).</li></ul> |

| 후크가 시간 초과되고 있습니다 |

기본 제한 시간은 30초입니다. 필요한 경우 timeoutSec을(를) 구성에 추가하십시오.
불필요한 작업을 방지하여 스크립트 성능을 최적화합니다.

| | 잘못된 JSON 출력 |

출력이 한 줄에 있는지 확인합니다.
Unix에서 JSON 출력을 압축하고 유효성을 검사하는 데 사용합니다 jq -c .
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 대한 사용자 수준 예제

문제 해결

디버깅

추가 읽기