Customize agent workflows with hooks

Run automated checks—like linting, formatting, or security scans—at key points during agent execution to enforce quality standards.

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

Creating a hook in a repository on GitHub

Create a new NAME.json file (where NAME describes the purpose of the file) 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 cloud agent.

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": [...]
  }
}

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

Include both a bash key (with a script for Linux and macOS) and a powershell key (for a script for Windows) to allow the hooks to run on all three operating systems. Copilot uses the appropriate key based on the user's operating system.

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

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.

Issue	Action
Hooks are not executing	Verify the JSON file is in the `.github/hooks/` directory. Check for valid JSON syntax (for example, `jq . hooks.json`). Ensure `version: 1` is specified in your `hooks.json` file. Verify the script you are calling from your hook is executable (`chmod +x script.sh`) Check that the script has a proper shebang (for example, `#!/bin/bash`)
Hooks are timing out	The default timeout is 30 seconds. Increase `timeoutSec` in the configuration if needed. Optimize script performance by avoiding unnecessary operations.
Invalid JSON output	Ensure the output is on a single line. On Unix, use `jq -c` to compact and validate the JSON output. On Windows, use the `ConvertTo-Json -Compress` command in PowerShell to do the same.

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 .

Customize agent workflows with hooks

Creating a hook in a repository on GitHub

Troubleshooting

Debugging

Further reading