{"meta":{"title":"GitHub Copilot CLI로 후크 사용하기","intro":"에이전트를 실행하는 동안 키 지점에서 사용자 지정 셸 명령을 사용하여 에이전트 동작을 확장 GitHub Copilot 합니다.","product":"GitHub Copilot","breadcrumbs":[{"href":"/ko/copilot","title":"GitHub Copilot"},{"href":"/ko/copilot/how-tos","title":"방법"},{"href":"/ko/copilot/how-tos/copilot-cli","title":"Copilot CLI"},{"href":"/ko/copilot/how-tos/copilot-cli/customize-copilot","title":"Copilot CLI 사용자 지정"},{"href":"/ko/copilot/how-tos/copilot-cli/customize-copilot/use-hooks","title":"후크 사용"}],"documentType":"article"},"body":"# GitHub Copilot CLI로 후크 사용하기\n\n에이전트를 실행하는 동안 키 지점에서 사용자 지정 셸 명령을 사용하여 에이전트 동작을 확장 GitHub Copilot 합니다.\n\n후크를 사용하면 에이전트를 실행하는 동안 키 지점에서 사용자 지정 셸 명령을 실행하여 에이전트의 GitHub Copilot 동작을 확장하고 사용자 지정할 수 있습니다. 사용 가능한 후크 트리거의 세부 정보를 포함하여 후크의 개념적 개요는 [후크에 대한 정보 GitHub Copilot](/ko/copilot/concepts/agents/hooks)을 참조하세요.\n\n## 전제 조건\n\n**Windows 사용자 전용:** 이 문서의 예제 후크는 Windows, Linux 및 macOS에서 실행되도록 설계되었습니다. Windows 경우 PowerShell을 사용하며 PowerShell 7.0 이상을 설치하고 PATH에 설치해야 합니다. 터미널에서 실행 `pwsh --version` 하여 PowerShell 버전을 확인할 수 있습니다. PowerShell을 설치하려면 `winget install Microsoft.PowerShell` 실행한 다음 터미널을 다시 시작합니다.\n\n## 리포지토리 수준 후크 만들기\n\n1. 리포지토리의 `NAME.json` 폴더에 새 `NAME` 파일(`.github/hooks/`는 파일의 용도를 설명함)을 만듭니다.\n\n2. 텍스트 편집기에서 다음 후크 템플릿을 복사하여 붙여넣습니다. 사용하지 않을 계획인 후크를 `hooks` 배열에서 제거합니다.\n\n ```json copy\n {\n \"version\": 1,\n \"hooks\": {\n \"sessionStart\": [...],\n \"sessionEnd\": [...],\n \"userPromptSubmitted\": [...],\n \"preToolUse\": [...],\n \"postToolUse\": [...],\n \"errorOccurred\": [...]\n }\n }\n ```\n\n3. `bash` 및 `powershell` 키에서 후크 구문을 구성하거나 직접 만든 스크립트 파일을 참조하세요.\n\n > \\[!NOTE]\n > 세 운영 체제에서 후크를 실행할 수 있도록 `bash` 키(Linux 및 macOS용 스크립트 포함)와 `powershell` 키(Windows 스크립트용)를 모두 포함합니다.\n > Copilot 는 사용자의 운영 체제에 따라 적절한 키를 사용합니다.\n\n * 이 예제에서는 후크를 사용하여 세션의 시작 날짜를 로그 파일에 출력하는 스크립트를 `sessionStart` 실행합니다.\n\n ```json copy\n \"sessionStart\": [\n {\n \"type\": \"command\",\n \"bash\": \"echo \\\"Session started: $(date)\\\" >> logs/session.log\",\n \"powershell\": \"Add-Content -Path logs/session.log -Value \\\"Session started: $(Get-Date)\\\"\",\n \"cwd\": \".\",\n \"timeoutSec\": 10\n }\n ],\n ```\n\n * 이 예제에서는 외부 `log-prompt` 스크립트를 호출합니다.\n\n ```json copy\n \"userPromptSubmitted\": [\n {\n \"type\": \"command\",\n \"bash\": \"./scripts/log-prompt.sh\",\n \"powershell\": \"./scripts/log-prompt.ps1\",\n \"cwd\": \"scripts\",\n \"env\": {\n \"LOG_LEVEL\": \"INFO\"\n }\n }\n ],\n ```\n\n 샘플 스크립트와 함께 에이전트 세션의 입력 JSON에 대한 전체 참조는 [GitHub Copilot 후크 참조](/ko/copilot/reference/hooks-reference)을 참조하세요.\n\n4. 파일을 리포지토리에 커밋하고 기본 분기에 병합합니다. 이제 에이전트 세션 동안 후크가 실행됩니다.\n\n## 사용자 수준 후크 만들기\n\n사용자 수준 후크는 리포지토리 수준 후크처럼 구성되지만 후크 파일은 홈 디렉터리 아래에 로컬로 저장됩니다.\n\nmacOS 및 Windows 대한 다음 예제에서는 CLI가 프롬프트에 응답하는 것을 완료하고 Copilot CLI 종료할 때 소리를 재생하고 메시지 상자를 표시하는 후크를 구성하는 방법을 보여 줍니다. Linux용 후크는 macOS 예제와 유사하지만, 소리를 재생하고 메시지를 표시하기 위해 Linux 도구를 사용합니다.\n\n### macOS에 대한 사용자 수준 예제\n\n1. `notification-hooks.json`에 `~/.copilot/hooks/`이라는 파일을 만듭니다.\n\n > \\[!NOTE]\n > `COPILOT_HOME`이 설정된 경우 `$COPILOT_HOME/hooks/`에 파일을 생성합니다.\n\n2. 다음 JSON을 복사하여 파일에 붙여넣습니다.\n\n ```json copy\n {\n \"version\": 1,\n \"hooks\": {\n \"agentStop\": [\n {\n \"type\": \"command\",\n \"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\\\"'\",\n \"timeoutSec\": 5\n }\n ],\n \"sessionEnd\": [\n {\n \"type\": \"command\",\n \"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\\\"'\",\n \"timeoutSec\": 5\n }\n ]\n }\n }\n ```\n\n3. Copilot CLI을(를) 시작하거나 다시 시작합니다.\n\n > \\[!NOTE]\n > 후크 구성에 대한 변경 내용은 CLI가 시작될 때 로드됩니다.\n\n4. 프롬프트를 입력하고 소리가 들리고 에이전트가 응답을 완료하고 CLI를 종료할 때 메시지 상자가 표시되는지 확인합니다.\n\n5. `notification-hooks.json` 파일을 삭제하여 이러한 후크를 제거합니다.\n\n### Windows 대한 사용자 수준 예제\n\n1. `notification-hooks.json`에 `%USERPROFILE%\\.copilot\\hooks\\`이라는 파일을 만듭니다.\n\n > \\[!NOTE]\n > `COPILOT_HOME`이 설정된 경우 `%COPILOT_HOME%\\hooks\\`에 파일을 생성합니다.\n\n2. 다음 JSON을 복사하여 파일에 붙여넣습니다.\n\n ```json copy\n {\n \"version\": 1,\n \"hooks\": {\n \"agentStop\": [\n {\n \"type\": \"command\",\n \"powershell\": \"Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Agent stopped.', 'Hook-generated message') | Out-Null\",\n \"timeoutSec\": 5\n }\n ],\n \"sessionEnd\": [\n {\n \"type\": \"command\",\n \"powershell\": \"Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Session ended.', 'Hook-generated message') | Out-Null\",\n \"timeoutSec\": 5\n }\n ]\n }\n }\n ```\n\n3. Copilot CLI을(를) 시작하거나 다시 시작합니다.\n\n > \\[!NOTE]\n > 후크 구성에 대한 변경 내용은 CLI가 시작될 때 로드됩니다.\n\n4. 프롬프트를 입력하고 소리가 들리고 에이전트가 응답을 완료하고 CLI를 종료할 때 메시지 상자가 표시되는지 확인합니다.\n\n5. `notification-hooks.json` 파일을 삭제하여 이러한 후크를 제거합니다.\n\n## 문제 해결\n\n후크를 사용하여 문제가 발생하면 다음 표를 사용하여 문제를 해결합니다.\n\n| Issue | 조치 |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| 후크가 실행되고 있지 않습니다. | | |\n| 후크가 시간 초과되고 있습니다 | |\n| 잘못된 JSON 출력 | |\n\n## 디버깅\n\n다음 메서드를 사용하여 후크를 디버그할 수 있습니다.\n\n* **스크립트에서 상세 로깅을 활성화하여** 입력 데이터를 점검하고 스크립트 실행을 추적합니다.\n\n ```shell copy\n #!/bin/bash\n set -x # Enable bash debug mode\n INPUT=$(cat)\n echo \"DEBUG: Received input\" >&2\n echo \"$INPUT\" >&2\n # ... rest of script\n ```\n\n* 테스트 입력을 후크에 파이핑하여 **로컬로 후크를 테스트**하여 해당 동작의 유효성을 검사합니다.\n\n ```shell copy\n # Create test input\n echo '{\"timestamp\":1704614400000,\"cwd\":\"/tmp\",\"toolName\":\"bash\",\"toolArgs\":\"{\\\"command\\\":\\\"ls\\\"}\"}' | ./my-hook.sh\n\n # Check exit code\n echo $?\n\n # Validate output is valid JSON\n ./my-hook.sh | jq .\n ```\n\n## 추가 읽기\n\n* [GitHub Copilot 후크 참조](/ko/copilot/reference/hooks-reference)\n* [GitHub Copilot 클라우드 에이전트 정보](/ko/copilot/concepts/agents/cloud-agent/about-cloud-agent)\n* [GitHub Copilot CLI 정보](/ko/copilot/concepts/agents/copilot-cli/about-copilot-cli)\n* [개발 환경 구성](/ko/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment)"}