Using hooks with GitHub Copilot agents

Using hooks with GitHub Copilot agents

Extend and customize GitHub Copilot agent behavior by executing custom shell commands at key points during agent execution.

Hooks allow you to extend and customize the behavior of GitHub Copilot agents by executing custom shell commands at key points during agent execution. For a conceptual overview of hooks—including details of the available hook triggers—see About hooks.

Creating a hook in a repository on GitHub

1. Create a new hooks.json file with the name of your choice in the .github/hooks/ folder of your repository. The hooks configuration file must be present on your repository's default branch to be used by Copilot coding agent. For GitHub Copilot CLI, hooks are loaded from your current working directory.

2. In your text editor, copy and paste the following hook template. Remove any hooks you don't plan on using from the hooks array.

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

3. Configure your hook syntax under the bash or powershell keys, or directly reference script files you have created.

   • This example runs a script that outputs the start date of the session to a log file using the sessionStart hook:

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

   • This example calls out to an external log-prompt script:

     "userPromptSubmitted": [
       {
         "type": "command",
         "bash": "./scripts/log-prompt.sh",
         "powershell": "./scripts/log-prompt.ps1",
         "cwd": "scripts",
         "env": {
           "LOG_LEVEL": "INFO"
         }
       }
     ],
     

     For a full reference on the input JSON from agent sessions along with sample scripts, see Hooks configuration.

4. Commit the file to the repository and merge it into the default branch. Your hooks will now run during agent sessions.

Troubleshooting

If you run into problems using hooks, use the following table to troubleshoot.

Debugging

You can debug hooks using the following methods:

• Enable verbose logging in the script to inspect the input data and trace script execution.

  #!/bin/bash
  set -x  # Enable bash debug mode
  INPUT=$(cat)
  echo "DEBUG: Received input" >&2
  echo "$INPUT" >&2
  # ... rest of script
  

• Test hooks locally by piping test input into your hook to validate its behavior:

  # 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 .
  

Further reading

• For more information about configuring hooks, see Hooks configuration
• For more information about Copilot coding agent, see About GitHub Copilot coding agent
• For more information about GitHub Copilot CLI, see About GitHub Copilot CLI
• For information about customizing the agent environment, see Customizing the development environment for GitHub Copilot coding agent