{"meta":{"title":"Customize agent workflows with hooks","intro":"Run automated checks—like linting, formatting, or security scans—at key points during agent execution to enforce quality standards.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/copilot","title":"GitHub Copilot"},{"href":"/en/copilot/how-tos","title":"How-tos"},{"href":"/en/copilot/how-tos/copilot-on-github","title":"Copilot on GitHub"},{"href":"/en/copilot/how-tos/copilot-on-github/customize-copilot","title":"Customize Copilot"},{"href":"/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent","title":"Customize cloud agent"},{"href":"/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/use-hooks","title":"Use hooks"}],"documentType":"article"},"body":"# Customize agent workflows with hooks\n\nRun automated checks—like linting, formatting, or security scans—at key points during agent execution to enforce quality standards.\n\nHooks 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](/en/copilot/concepts/agents/cloud-agent/about-hooks).\n\n## Creating a hook in a repository on GitHub\n\n1. 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 cloud agent. For GitHub Copilot CLI, hooks are loaded from your current working directory.\n\n2. In your text editor, copy and paste the following hook template. Remove any hooks you don't plan on using from the `hooks` array.\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. Configure your hook syntax under the `bash` or `powershell` keys, or directly reference script files you have created.\n\n   * This example runs a script that outputs the start date of the session to a log file using the `sessionStart` hook:\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   * This example calls out to an external `log-prompt` script:\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     For a full reference on the input JSON from agent sessions along with sample scripts, see [Hooks configuration](/en/copilot/reference/hooks-configuration).\n\n4. Commit the file to the repository and merge it into the default branch. Your hooks will now run during agent sessions.\n\n## Troubleshooting\n\nIf you run into problems using hooks, use the following table to troubleshoot.\n\n| Issue                   | Action                                                                                                                                                                                                                                                                                                                                                                                                |\n| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Hooks are not executing | <ul><li>Verify the JSON file is in the `.github/hooks/` directory.</li><li>Check for valid JSON syntax (for example, `jq .  hooks.json`).</li><li>Ensure `version: 1` is specified in your `hooks.json` file.</li><li>Verify the script you are calling from your hook is executable (`chmod +x script.sh`)</li><li>Check that the script has a proper shebang (for example, `#!/bin/bash`)</li></ul> |\n| Hooks are timing out    | <ul><li>The default timeout is 30 seconds. Increase `timeoutSec` in the configuration if needed.</li><li>Optimize script performance by avoiding unnecessary operations.</li></ul>                                                                                                                                                                                                                    |\n| Invalid JSON output     | <ul><li>Ensure the output is on a single line.</li><li>On Unix, use `jq -c` to compact and validate the JSON output.</li><li>On Windows, use the `ConvertTo-Json -Compress` command in PowerShell to do the same.</li></ul>                                                                                                                                                                           |\n\n## Debugging\n\nYou can debug hooks using the following methods:\n\n* **Enable verbose logging** in the script to inspect the input data and trace script execution.\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* **Test hooks locally** by piping test input into your hook to validate its behavior:\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## Further reading\n\n* [Hooks configuration](/en/copilot/reference/hooks-configuration)\n* [About GitHub Copilot cloud agent](/en/copilot/concepts/agents/cloud-agent/about-cloud-agent)\n* [About GitHub Copilot CLI](/en/copilot/concepts/agents/about-copilot-cli)\n* [Configure the development environment](/en/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment)"}