Utilisation de crochets avec CLI GitHub Copilot

Les hooks vous permettent d’étendre et de personnaliser le comportement de GitHub Copilot agents en exécutant des commandes shell personnalisées aux points clés pendant l’exécution des agents. Pour obtenir une vue d’ensemble conceptuelle des hooks, y compris les détails des déclencheurs de hook disponibles, consultez À propos des crochets pour GitHub Copilot.

Conditions préalables

          **For Windows only :** Les exemples de cet article utilisent PowerShell. Si vous utilisez Windows, powerShell 7.0 ou version ultérieure doit être installé et dans votre chemin d'accès. Vous pouvez vérifier votre version de PowerShell en s’exécutant `pwsh --version` dans un terminal. Pour installer PowerShell, exécutez `winget install Microsoft.PowerShell` puis redémarrez votre terminal.

Création d’un hook au niveau du référentiel

Créez un NAME.json fichier (où NAME décrit l’objectif du fichier) dans le .github/hooks/ dossier de votre dépôt.

Dans votre éditeur de texte, copiez et collez le modèle de hook suivant. Supprimez les éléments que vous ne prévoyez pas d’utiliser dans le tableau hooks.

JSON

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

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

Configurez la syntaxe de votre hook sous les clés bash et powershell, ou référencez directement les fichiers de script que vous avez créés.

Remarque

Incluez à la fois une clé bash (avec un script pour Linux et macOS) et une clé powershell (pour un script pour Windows) afin d’autoriser les hooks à s’exécuter sur les trois systèmes d’exploitation. Copilot utilise la clé appropriée en fonction du système d’exploitation de l’utilisateur.

Cet exemple exécute un script qui génère la date de début de la session dans un fichier journal à l’aide du sessionStart hook :

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

Cet exemple appelle un script externe 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"
    }
  }
],

Pour obtenir une référence complète sur l’entrée JSON à partir de sessions d’agent, ainsi que des exemples de scripts, consultez Références sur les hooks GitHub Copilot.

Validez le fichier dans le référentiel et fusionnez-le dans la branche par défaut. Vos hooks s’exécuteront désormais pendant les sessions de l’agent.

Création d’un hook au niveau de l’utilisateur

Les hooks au niveau de l’utilisateur sont configurés de la même manière que les hooks au niveau du référentiel, mais les fichiers de hooks sont stockés localement dans votre répertoire personnel.

Les exemples suivants pour macOS et Windows montrent comment configurer des hooks qui déclenchent la lecture d’un son et affichent une boîte de dialogue lorsque le CLI a fini de répondre à une invite, ainsi que lorsque vous quittez Copilot pour CLI. Les hooks pour Linux sont similaires à l’exemple macOS, mais utilisent des outils Linux pour lire des sons et afficher des messages.

Exemple de niveau utilisateur pour macOS

Créez un fichier appelé notification-hooks.json dans ~/.copilot/hooks/.

Remarque

Si COPILOT_HOME est défini, créez le fichier dans $COPILOT_HOME/hooks/.

Copiez et collez le code JSON suivant dans le fichier :

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

Démarrez ou redémarrez. Copilot pour CLI

Remarque

Les modifications apportées aux configurations de raccordement sont chargées au démarrage de l’interface CLI.
Entrez une invite et vérifiez que vous entendez un son et voyez une fenêtre de message lorsque l'agent a terminé de répondre et lorsque vous quittez l'interface en ligne de commande (CLI).
Supprimez le notification-hooks.json fichier pour supprimer ces hooks.

Exemple de niveau utilisateur pour Windows

Créez un fichier appelé notification-hooks.json dans %USERPROFILE%\.copilot\hooks\.

Remarque

Si COPILOT_HOME est défini, créez le fichier dans %COPILOT_HOME%\hooks\.

Copiez et collez le code JSON suivant dans le fichier :

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

Démarrez ou redémarrez. Copilot pour CLI

Remarque

Les modifications apportées aux configurations de raccordement sont chargées au démarrage de l’interface CLI.
Entrez une invite et vérifiez que vous entendez un son et voyez une fenêtre de message lorsque l'agent a terminé de répondre et lorsque vous quittez l'interface en ligne de commande (CLI).
Supprimez le notification-hooks.json fichier pour supprimer ces hooks.

Résolution des problèmes

Si vous rencontrez des problèmes à l’aide de crochets, utilisez le tableau suivant pour résoudre les problèmes.

Problème	Action
Les hooks ne s’exécutent pas	Vérifiez que le fichier JSON se trouve dans le `.github/hooks/` répertoire. Recherchez la syntaxe JSON valide (par exemple). `jq . hooks.json` **

Assurez-vous que version: 1 est spécifié dans le fichier hooks.json.

Vérifiez que le script que vous appelez à partir de votre hook est exécutable (chmod +x script.sh)

Vérifiez que le script a un shebang approprié (par exemple, #!/bin/bash)

| | Les crochets expirent |

Le délai d’expiration par défaut est de 30 secondes. Augmentez timeoutSec dans la configuration si nécessaire.
Optimisez les performances des scripts en évitant les opérations inutiles.

| | Sortie JSON non valide |

Vérifiez que la sortie se trouve sur une seule ligne.
Sur Unix, utilisez jq -c pour compacter et valider la sortie JSON.
Sur Windows, utilisez la commande ConvertTo-Json -Compress dans PowerShell pour effectuer la même opération.

Débogage

Vous pouvez déboguer des hooks à l’aide des méthodes suivantes :

Activez la journalisation détaillée dans le script pour inspecter les données d’entrée et tracer l'exécution du script.

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

Testez les hooks localement en redirigeant l’entrée de test dans votre hook pour valider son comportement :

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 .

Utilisation de crochets avec CLI GitHub Copilot

Dans cet article

Conditions préalables

Création d’un hook au niveau du référentiel

Création d’un hook au niveau de l’utilisateur

Exemple de niveau utilisateur pour macOS

Exemple de niveau utilisateur pour Windows

Résolution des problèmes

Débogage

Lectures complémentaires