Text of docs.github.com › en › copilot › reference › hooks-reference as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

GitHub Copilot hooks reference - GitHub Docs

Skip to main content Skip to content Collapse sidebar Expand sidebar GitHub Copilot hooks reference Find hook events, configuration formats, and input payloads for hooks in Copilot CLI and Copilot in the cloud. In this article Introduction Hooks are external commands that execute at specific lifecycle points during a session, enabling custom automation, security controls, and integrations. Hooks are supported in two Copilot surfaces: Copilot CLI and Copilot in the cloud.

Most of the configuration format and event payloads are identical, but the execution environment and the set of events that can fire differ. Throughout this article, behavior that differs between the two surfaces is called out in "CLI only" and "Cloud agent only" notes. Anything not marked applies to both. Hooks locations The locations where hooks run, and where you can store hook configuration files, depend on the surface: Copilot CLI — hooks run on the developer's local machine in the same shell as the CLI.

All hook events described in this article are supported by the CLI. Hooks are loaded from the following sources in order (policy, then user, then project, then plugins) and combined. When the same event appears in multiple sources, all hook entries from all sources are run. Policy-level hook files — JSON files in the platform-appropriate policy directory, loaded in alphabetical order. Policy hooks are machine-wide and load before all other hooks.

They cannot be disabled by disableAllHooks and are available regardless of folder trust state. See Policy hooks below. Repository-level hook files — .github/hooks/*.json in the repository root. User-level hook files — *.json files in the user-level hooks directory. By default this is ~/.copilot/hooks/ on macOS and Linux, or %USERPROFILE%\.copilot\hooks\ on Windows. If COPILOT_HOME is set, it is $COPILOT_HOME/hooks/ .

Inline hooks block in repository settings — the hooks field at the top level of .github/copilot/settings.json (Git committed) or .github/copilot/settings.local.json (typically gitignored and user specific) in the repository. Cross-tool .claude/settings.json and .claude/settings.local.json files in the repository are also read. Inline hooks block in user-level config — the hooks field at the top level of ~/.copilot/settings.json .

The CLI no longer reads ~/.copilot/config.json for hooks. Hooks contributed by installed plugins — declared by each plugin in its own hooks.json (or under hooks/hooks.json ) inside the plugin's installation directory. Copilot in the cloud — hooks run inside the ephemeral Linux sandbox that cloud agent provisions for each job. The sandbox is non-interactive, has a constrained network, and is destroyed when the job ends.

A subset of events fires, and only bash (or command ) entries are honored. Hook configuration is loaded from .github/hooks/*.json files in the cloned repository. Policy hooks Note Copilot CLI only. Policy hooks are not supported under Copilot in the cloud. Policy hooks are machine-wide hooks loaded by administrators. They load before all other hooks and cannot be disabled by disableAllHooks . Policy hooks are discovered from two sources: Filesystem : JSON files in the platform-appropriate policy directory, loaded in alphabetical order: Linux/macOS: /etc/github-copilot/policy.d/*.json Windows: C:\ProgramData\GitHub\Copilot\policy.d\*.json Windows Registry : Values under HKLM\Software\Policies\GitHub\Copilot (each subkey holds a Policy REG_SZ value containing a JSON policy document).

Policy hook files use the same hook configuration format as user and project hooks ( { "version": 1, "hooks": { ... } } ). On POSIX systems, policy files must be owned by root and must not be group- or world-writable. Policy hooks are intended for use by enterprise IT administrators and require elevated privileges to install. End users cannot modify them. Policy hooks always run on the host, even when the session sandbox is enabled—see Sandboxed sessions .

Agent-scoped hooks Note Copilot CLI only. Declare a hooks event map in a custom agent's frontmatter to run command or HTTP hooks only while that agent is selected. These hooks run in addition to session, user, repository, plugin, and policy hooks. --- name: formatter description: Formats changed files hooks: PostToolUse: - type: command command: ./scripts/format-changed-files.sh windows: ./scripts/format-changed-files.ps1 --- Format the files you change.

Behavior Details Event names Runtime names such as postToolUse and aliases such as PostToolUse are accepted. Commands command is the fallback. windows , linux , and osx override it per platform. Paths resolve from the repository root. Subagent Stop A subagent's scoped Stop ( agentStop ) hooks run at SubagentStop . After eight consecutive scoped blocks, further blocks are ignored. Trust Repository and inherited-agent hooks require workspace admission.

Hook-disable settings, enterprise restrictions, and timeouts still apply. Unsupported Remote or organization-hosted agent definitions do not run scoped hooks. Cloud agent execution environment This section applies to Copilot in the cloud only . It describes constraints that affect how you write hook scripts and configure hook entries for cloud agent jobs. Property Value Operating system Linux. Only the bash field on command hooks is honored; powershell entries are ignored.

The cross-platform command field is honored as a fallback. Working directory /workspace when a repository is cloned, otherwise /root . Use this path when setting cwd on a hook entry or when referencing files from a script. Filesystem Ephemeral. Files written by hooks (logs, CSVs, transcripts) are discarded when the job ends. To retain hook output, send it via an http hook entry. Outbound network Restricted by the cloud agent firewall.

By default only GitHub and Copilot hostnames are reachable; reaching any other host (for example https:/ / hooks.example.com ) requires an admin-configured firewall allow rule. The cloud agent firewall applies only to Copilot in the cloud jobs. Available environment variables GITHUB_COPILOT_ API_TOKEN and GITHUB_COPILOT_ GIT_TOKEN are set in the sandbox. COPILOT_AGENT_ PROMPT holds the prompt the job was invoked with.

HOME is set to /root , so any hook script that resolves ~/... paths writes into the ephemeral sandbox. GITHUB_TOKEN is not set. Interactivity Fully non-interactive. The agent runs with all tool permissions pre-granted, so no permission dialogs are shown and no notifications are surfaced to a user. Configuration discovery In a cloud agent job, the only hook configuration that exists by default is .github/ hooks/ *.json inside the cloned repository.

The sandbox does not ship with user-level hook files, settings.json , config.json , or installed plugins. Hook configuration format Hook configuration files use JSON format with version 1 . Note If a hook configuration file loaded from a directory (for example, .github/hooks/ ) contains a malformed hook item, only that item is dropped and logged—valid sibling hooks in the same file still load. Structural errors (invalid JSON, a bad version , or a non-array event list) still reject the entire file.

Hooks defined inline in settings.json remain strict: any item-level validation error rejects the whole hooks field. Other configuration files always load independently. The CLI prints ! Invalid hook configuration in FILE: REASON for each skipped file or entry when repository hooks load at startup or after /cd into a repository. Command hooks Command hooks run shell scripts or executables and are supported on all hook types.

Note Cloud agent only. Cloud agent runs hooks in a Linux sandbox. Only the bash field is honored; powershell entries are ignored. The cross-platform command field is honored as a fallback. { "version" : 1 , "hooks" : { "preToolUse" : [ { "type" : "command" , "bash" : "YOUR_BASH_COMMAND" , "powershell" : "YOUR_POWERSHELL_COMMAND" , "cwd" : "OPTIONAL/WORKING/DIRECTORY"

The rest of this page is on the live site.