{"meta":{"title":"Verwenden von Hooks mit GitHub Copilot CLI","intro":"Erweitern des GitHub Copilot Agentverhaltens mit benutzerdefinierten Shellbefehlen an Schlüsselpunkten während der Agentausführung.","product":"GitHub Copilot","breadcrumbs":[{"href":"/de/copilot","title":"GitHub Copilot"},{"href":"/de/copilot/how-tos","title":"Vorgehensweisen"},{"href":"/de/copilot/how-tos/copilot-cli","title":"Copilot CLI"},{"href":"/de/copilot/how-tos/copilot-cli/customize-copilot","title":"Das Copilot CLI anpassen"},{"href":"/de/copilot/how-tos/copilot-cli/customize-copilot/use-hooks","title":"Verwenden Sie Hooks"}],"documentType":"article"},"body":"# Verwenden von Hooks mit GitHub Copilot CLI\n\nErweitern des GitHub Copilot Agentverhaltens mit benutzerdefinierten Shellbefehlen an Schlüsselpunkten während der Agentausführung.\n\nHooks ermöglichen es Ihnen, das Verhalten von GitHub Copilot Agents zu erweitern und anzupassen, indem Sie benutzerdefinierte Shellbefehle an wichtigen Stellen während der Agentausführung ausführen. Eine konzeptionelle Übersicht über Hooks – einschließlich Details zu den verfügbaren Hook-Triggern – finden Sie unter [Informationen zu Hooks für GitHub Copilot](/de/copilot/concepts/agents/hooks).\n\n## Voraussetzung\n\n**nur Windows Benutzer:** Die Beispiel-Hooks in diesem Artikel sind so konzipiert, dass sie auf Windows, Linux und macOS ausgeführt werden. Für Windows verwenden sie PowerShell und erfordern, dass PowerShell 7.0 oder höher und in Ihrem PATH installiert ist. Sie können Ihre PowerShell-Version überprüfen, indem Sie `pwsh --version` in einem Terminal ausführen. Um PowerShell zu installieren, führen Sie `winget install Microsoft.PowerShell` aus, und starten Sie das Terminal neu.\n\n## Erstellen eines Hooks auf Repositoryebene\n\n1. Erstellen Sie eine neue `NAME.json`-Datei (wobei `NAME` den Zweck der Datei beschreibt) im Ordner `.github/hooks/` Ihres Repositorys.\n\n2. Kopieren Sie in Ihrem Text-Editor die folgende Hook-Vorlage, und fügen Sie sie ein. Entfernen Sie alle Hooks, die Sie nicht aus dem `hooks` Array verwenden möchten.\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. Konfigurieren Sie Ihre Hook-Syntax unter den Schlüsseln `bash` und `powershell`, oder referenzieren Sie direkt Skriptdateien, die Sie erstellt haben.\n\n > \\[!NOTE]\n > Schließen Sie sowohl einen `bash`-Schlüssel (mit einem Skript für Linux und macOS) als auch einen `powershell`-Schlüssel (für ein Skript für Windows) ein, damit die Hooks auf allen drei Betriebssystemen ausgeführt werden können.\n > Copilot verwendet den entsprechenden Schlüssel basierend auf dem Betriebssystem des Benutzers.\n\n * In diesem Beispiel wird ein Skript ausgeführt, das das Startdatum der Sitzung mithilfe des `sessionStart` Hooks in eine Protokolldatei ausgibt:\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 * In diesem Beispiel wird ein externes `log-prompt` Skript aufgerufen:\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 Eine vollständige Referenz zu den Eingabe-JSON aus Agentsitzungen sowie Beispielskripts finden Sie unter [GitHub Copilot-Hooks-Referenz](/de/copilot/reference/hooks-reference).\n\n4. Commit die Datei in das Repository und füge sie in den Standard Branch ein. Ihre Hooks werden jetzt während Agentsitzungen ausgeführt.\n\n## Erstellen eines Hooks auf Benutzerebene\n\nHooks auf Benutzerebene werden wie Hooks auf Repositoryebene konfiguriert, aber die Hookdateien werden lokal unter Ihrem Heimverzeichnis gespeichert.\n\nDie folgenden Beispiele für macOS und Windows zeigen, wie Hooks konfiguriert werden, die einen Sound wiedergeben und ein Meldungsfeld anzeigen, wenn die CLI die Antwort auf eine Eingabeaufforderung beendet hat und wenn Sie Copilot CLI beenden. Hooks für Linux wären dem macOS-Beispiel ähnlich, würden aber Linux-Tools zum Wiedergeben von Sounds und anzeigen von Nachrichten verwenden.\n\n### Beispiel für MacOS auf Benutzerebene\n\n1. Erstellen Sie eine Datei namens `notification-hooks.json` in `~/.copilot/hooks/`.\n\n > \\[!NOTE]\n > Falls `COPILOT_HOME` festgelegt ist, erstellen Sie die Datei in `$COPILOT_HOME/hooks/`.\n\n2. Kopieren Sie den folgenden JSON-Code, und fügen Sie ihn in die Datei ein:\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. Starten Sie, oder starten Sie neu Copilot CLI.\n\n > \\[!NOTE]\n > Änderungen an Hook-Konfigurationen werden geladen, wenn die CLI gestartet wird.\n\n4. Geben Sie eine Eingabeaufforderung ein, und überprüfen Sie, ob Sie einen Sound hören, und sehen Sie ein Meldungsfeld, wenn der Agent fertig ist, und wenn Sie die CLI beenden.\n\n5. Löschen Sie die `notification-hooks.json` Datei, um diese Hooks zu entfernen.\n\n### Beispiel für Windows auf Benutzerebene\n\n1. Erstellen Sie eine Datei namens `notification-hooks.json` in `%USERPROFILE%\\.copilot\\hooks\\`.\n\n > \\[!NOTE]\n > Falls `COPILOT_HOME` festgelegt ist, erstellen Sie die Datei in `%COPILOT_HOME%\\hooks\\`.\n\n2. Kopieren Sie den folgenden JSON-Code, und fügen Sie ihn in die Datei ein:\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. Starten Sie, oder starten Sie neu Copilot CLI.\n\n > \\[!NOTE]\n > Änderungen an Hook-Konfigurationen werden geladen, wenn die CLI gestartet wird.\n\n4. Geben Sie eine Eingabeaufforderung ein, und überprüfen Sie, ob Sie einen Sound hören, und sehen Sie ein Meldungsfeld, wenn der Agent fertig ist, und wenn Sie die CLI beenden.\n\n5. Löschen Sie die `notification-hooks.json` Datei, um diese Hooks zu entfernen.\n\n## Problembehandlung\n\nWenn Probleme bei der Verwendung von Hooks auftreten, verwenden Sie die folgende Tabelle, um Probleme zu beheben.\n\n| Thema | Action |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Hooks werden nicht ausgeführt | |\n| Hooks laufen ab | |\n| Ungültige JSON-Ausgabe | |\n\n## Fehlersuche\n\nSie können Hooks mit den folgenden Methoden debuggen:\n\n* **Aktivieren Sie die ausführliche Protokollierung** im Skript, um die Eingabedaten zu überprüfen und die Skriptausführung nachzuverfolgen.\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* **Testen Sie Hooks lokal**, indem Sie die Testeingaben in Ihre Hooks weiterleiten, um ihr Verhalten zu überprüfen.\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## Weiterführende Lektüre\n\n* [GitHub Copilot-Hooks-Referenz](/de/copilot/reference/hooks-reference)\n* [Informationen zu GitHub Copilot Cloud-Agent](/de/copilot/concepts/agents/cloud-agent/about-cloud-agent)\n* [Informationen zu GitHub Copilot CLI](/de/copilot/concepts/agents/copilot-cli/about-copilot-cli)\n* [Konfigurieren der Entwicklungsumgebung](/de/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment)"}