Skip to content

use-hooks.md

Latest commit

 

History

History
110 lines (85 loc) · 4.13 KB

use-hooks.md

File metadata and controls

110 lines (85 loc) · 4.13 KB
Raw
title Using hooks with {% data variables.copilot.copilot_cli %}
shortTitle Use hooks
intro Extend {% data variables.product.prodname_copilot %} agent behavior with custom shell commands at key points during agent execution.
versions
feature
copilot
contentType how-tos
category
Author and optimize with Copilot
Build with Copilot CLI
redirect_from
/copilot/how-tos/copilot-cli/use-hooks
docsTeamMetrics
copilot-cli

{% data reusables.copilot.cloud-agent.hooks-intro %}

Prerequisite

Windows users only: The example hooks in this article are designed to run on Windows, Linux, and macOS. For Windows, they use PowerShell and require you to have PowerShell 7.0 or later installed and in your PATH. You can check your PowerShell version by running pwsh --version in a terminal. To install PowerShell, run winget install Microsoft.PowerShell then restart your terminal.

Creating a repository-level hook

  1. Create a new NAME.json file (where NAME describes the purpose of the file) in the .github/hooks/ folder of your repository.

{% data reusables.copilot.cloud-agent.create-hooks-instructions %}

Creating a user-level hook

User-level hooks are configured just like repository-level hooks, but the hook files are stored locally, below your home directory.

The following examples for macOS and Windows show how to configure hooks that will play a sound and display a message box when the CLI finishes responding to a prompt, and when you quit {% data variables.copilot.copilot_cli_short %}. Hooks for Linux would be similar to the macOS example, but would use Linux tools for playing sounds and displaying messages.

User-level example for macOS

  1. Create a file called notification-hooks.json in ~/.copilot/hooks/.

    [!NOTE] If COPILOT_HOME is set, create the file in $COPILOT_HOME/hooks/.

  2. Copy and paste the following JSON into the file:

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

{% data reusables.copilot.cloud-agent.hooks-example-steps %}

User-level example for Windows

  1. Create a file called notification-hooks.json in %USERPROFILE%\.copilot\hooks\.

    [!NOTE] If COPILOT_HOME is set, create the file in %COPILOT_HOME%\hooks\.

  2. Copy and paste the following JSON into the file:

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

{% data reusables.copilot.cloud-agent.hooks-example-steps %}

Troubleshooting

{% data reusables.copilot.cloud-agent.troubleshoot-hooks %}

Further reading