Quick video on hooks

---

How to Use Hooks in GitHub Copilot for VS Code: Automate, Secure, and Extend Your AI Agents

Hooks in GitHub Copilot for Visual Studio Code allow you to execute custom shell commands at key lifecycle points during agent sessions. This powerful feature lets you automate workflows, enforce security policies, validate operations, and integrate with external tools—making your AI agents smarter and safer.

Note: Hooks are currently in Preview. The configuration format and behavior may change in future releases.

Why Use Hooks?

Hooks provide deterministic, code-driven automation. Unlike instructions or custom prompts, hooks execute your code at specific lifecycle points with guaranteed outcomes. Common use cases include:

• Enforcing security policies: Block dangerous commands like rm -rf or DROP TABLE before they execute.
• Automating code quality: Run formatters, linters, or tests automatically after file modifications.
• Creating audit trails: Log every tool invocation, command execution, or file change for compliance and debugging.
• Injecting context: Add project-specific information, API keys, or environment details to help the agent make better decisions.
• Controlling approvals: Automatically approve safe operations while requiring confirmation for sensitive ones.

Quick Start: Your First Hook

Here’s how to create a hook that runs Prettier after every file edit:

1. Create a .github/hooks/format.json file in your workspace:

jsonCopy
{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\""
      }
    ]
  }
}

2. Save the file. VS Code will automatically load the hook. The next time the agent edits a file, Prettier will run on the changed file.
3. Check the GitHub Copilot Chat Hooks output channel to verify the hook executed.

Supported Hook Events

VS Code supports eight hook events that fire at specific points during an agent session:

Hook Event	When It Fires	Common Use Cases
SessionStart	User submits the first prompt of a session	Initialize resources, log session start
UserPromptSubmit	User submits a prompt	Audit requests, inject system context
PreToolUse	Before agent invokes any tool	Block dangerous ops, require approval, modify input
PostToolUse	After tool completes successfully	Run formatters, log results, trigger actions
PreCompact	Before conversation context is compacted	Export context, save state
SubagentStart	Subagent is spawned	Track usage, initialize resources
SubagentStop	Subagent completes	Aggregate results, cleanup resources
Stop	Agent session ends	Generate reports, cleanup, send notifications

Configuring Hooks

Hooks are configured in JSON files stored in your workspace or user directory. Common locations include:

• .github/hooks/*.json (workspace)
• .claude/settings.json or .claude/settings.local.json (workspace)
• ~/.copilot/hooks or ~/.claude/settings.json (user)

You can customize which hook files are loaded using the chat.hookFilesLocations setting in VS Code.

Hook Command Properties

Each hook entry must have type: "command" and at least one command property. You can specify OS-specific commands, working directory, environment variables, and timeouts.

Example with OS-specific commands:

jsonCopy
{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "./scripts/format.sh",
        "windows": "powershell -File scripts\\format.ps1",
        "linux": "./scripts/format-linux.sh",
        "osx": "./scripts/format-mac.sh"
      }
    ]
  }
}

Hook Input and Output

Hooks communicate with VS Code through stdin (input) and stdout (output) using JSON. They can influence agent behavior by returning fields like continue, stopReason, and systemMessage.

• Exit code 2: Blocks an operation (blocking error)
• continue: false: Stops the entire agent session
• hookSpecificOutput: Fine-grained control for each hook event
• systemMessage: Displays a warning to the user

Example: Blocking Dangerous Commands

To block destructive commands, use a PreToolUse hook that checks the tool input and denies execution if it matches a dangerous pattern.

Learn More

• Official documentation on hooks
• Quick video on hooks

Hooks are a powerful way to automate, secure, and extend your AI agent workflows in VS Code. Try them out to supercharge your development process!