Skip to main content

​
Hooks Overview

Hooks enable automated workflows triggered by specific events during GitHub Copilot coding agent sessions, such as session start, session end, user prompts, and tool usage.

​
What Are Hooks?

Hooks are event-driven automations that execute custom scripts or commands during GitHub Copilot coding agent sessions. They follow the GitHub Copilot hooks specification and provide a powerful way to extend your development workflow.

Session Tracking

Log session starts and ends for audit trails and usage analytics

Auto-Commit

Automatically commit and push changes when sessions end

Governance

Scan prompts for security threats and compliance violations

Custom Workflows

Integrate with external tools and services

​
Hook Structure

Each hook is a folder containing:
1

README.md with Frontmatter

A documentation file with required metadata:
---
name: 'Hook Name'
description: 'What this hook does'
tags: ['category', 'type']
---
2

hooks.json Configuration

A JSON file defining hook events and commands:
{
  "version": 1,
  "hooks": {
    "sessionStart": [...],
    "sessionEnd": [...],
    "userPromptSubmitted": [...]
  }
}
3

Bundled Scripts & Assets

Helper scripts, utilities, or configuration files referenced in hooks.json

​
Available Hook Events

Hooks can be triggered by the following events during a Copilot coding agent session:
Triggered when a new Copilot coding agent session begins.Common Use Cases:
  • Initialize session logging
  • Set up environment variables
  • Load project-specific configurations
  • Start time tracking
Triggered when a Copilot coding agent session ends.Common Use Cases:
  • Auto-commit and push changes
  • Generate session reports
  • Clean up temporary files
  • Log session duration and statistics
Triggered each time the user submits a prompt to the agent.Common Use Cases:
  • Log user prompts for audit
  • Scan prompts for security threats
  • Track prompt patterns and analytics
  • Filter or validate prompts
Triggered before the agent uses a tool.Common Use Cases:
  • Validate tool parameters
  • Log tool usage for compliance
  • Set up tool-specific environments
  • Implement custom authorization
Triggered after the agent uses a tool.Common Use Cases:
  • Log tool results
  • Clean up tool artifacts
  • Track tool performance
  • Trigger follow-up actions
Triggered when an error occurs during the session.Common Use Cases:
  • Log errors for debugging
  • Send error notifications
  • Trigger recovery procedures
  • Collect diagnostic information

​
Hook Configuration

The hooks.json file defines which commands run on which events. Here’s a complete example:
hooks.json
{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": ".github/hooks/session-logger/log-session-start.sh",
        "cwd": ".",
        "timeoutSec": 5
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": ".github/hooks/session-logger/log-session-end.sh",
        "cwd": ".",
        "timeoutSec": 5
      }
    ],
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": ".github/hooks/session-logger/log-prompt.sh",
        "cwd": ".",
        "env": {
          "LOG_LEVEL": "INFO"
        },
        "timeoutSec": 5
      }
    ]
  }
}

​
Configuration Fields

FieldTypeDescription
versionnumberHook specification version (currently 1)
typestringCommand type (currently only "command" supported)
bashstringPath to the script to execute
cwdstringWorking directory for the command (. for repository root)
envobjectEnvironment variables to pass to the script
timeoutSecnumberMaximum execution time in seconds

​
Installation

To install a hook in your repository:
1

Copy Hook Folder

Copy the hook folder to your repository’s .github/hooks/ directory:
cp -r hooks/session-logger .github/hooks/
2

Make Scripts Executable

Ensure any bundled scripts are executable:
chmod +x .github/hooks/session-logger/*.sh
3

Commit to Default Branch

Commit the hook to your repository’s default branch:
git add .github/hooks/session-logger
git commit -m "Add session logger hook"
git push
4

Hooks Activate Automatically

Hooks automatically execute during Copilot coding agent sessions once committed to the default branch.

​
Best Practices

Keep Scripts Fast

Use short timeouts and optimize scripts to avoid blocking the agent

Handle Errors Gracefully

Always include error handling - hooks should never crash the session

Respect Privacy

Don’t log sensitive data like full prompts or credentials

Make Hooks Optional

Support environment variables to disable hooks when needed

​
Security Considerations

  • Validate inputs: Never trust data from hooks without validation
  • Use least privilege: Run scripts with minimal permissions
  • Avoid external calls: Minimize network requests in hooks
  • Protect logs: Add log directories to .gitignore
  • Review scripts: Audit hook scripts before installing them

​
When to Use Hooks

Hooks are ideal for:
  • Automated session logging and audit trails
  • Auto-committing changes at session end
  • Tracking usage analytics for teams
  • Integrating with external tools (Slack, monitoring systems)
  • Enforcing governance policies on prompts and tool usage
  • Custom session workflows specific to your project
For more complex repository automation that runs in GitHub Actions, see Agentic Workflows.

​
Next Steps

Browse Hook Catalog

Explore available hooks and installation examples

GitHub Copilot Hooks Spec

Read the official hooks specification

Build docs developers (and LLMs) love

Get started for freeTalk to us