Text of code.visualstudio.com › docs › agent-customization › hooks as Styx crawled it on Nov 18, 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

Configure agent hooks in Visual Studio Code

AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. Join VS Code at Microsoft Ignite or catch the sessions online. A year of VS Code, wrapped. Explore the highlights. Configure agent hooks in Visual Studio Code View as Markdown Ask in VS Code Ask in VS Code Insiders Hooks run custom actions at specific points in the agent's workflow, such as before or after a tool runs.

Use them to add context, validate a tool call, run a formatter, or record an event without relying on the model to request the action. Use the Agent Customizations editor to create and manage hooks for the shared Copilot runtime. This article walks through creating a hook, adding its supporting script, and verifying the result. If you already have hooks for another harness, start with Migrate hooks . Migration includes user folders, settings, custom agents, and plugins, not only repository files.

Note Individual provider implementations can have a different lifecycle status and release schedule. Important Your organization might restrict which hooks can run. Claude and Codex harnesses are disabled when Copilot enterprise-managed settings apply , unless your administrator explicitly permits them. Contact the IT team that deployed the settings to discuss access. Administrators can learn how to manage hooks in enterprise environments .

Choose the hook implementation for your session Select Copilot from the Session Target UI control to use the Copilot harness. VS Code, the GitHub Copilot app, and GitHub Copilot CLI share this harness and its hook format. You do not need to install or use the CLI to configure hooks in the editor. Use the Copilot hooks reference for command configuration, event inputs, and outputs. Other session targets use their own hook implementations: Session Target choice Configuration and event reference Claude Claude hooks reference Codex Codex hooks documentation Cloud sessions Cloud sessions is experimental and might change or be removed. use the Copilot harness in a managed environment.

Local hook files aren't automatically copied to that environment. Check the configuration available in the cloud workspace rather than assuming that hooks on your machine apply there. The Local harness The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation . has a separate Local hooks reference . Use it to interpret existing hooks during migration, not as the schema for a new Copilot hook.

Migrate hooks between harnesses Sharing a hook file location does not establish runtime compatibility. Event naming can select a different payload, tool names and arguments can change, and output or error behavior can differ. Follow the hook migration procedure and compatibility matrix before reusing a hook. Select the destination harness and start a test session; changing only the language model does not test migration.

Reuse hooks from a plugin For an existing automation workflow, browse customization marketplaces for a plugin that includes hooks and their supporting scripts. Before installing, review the scripts, required executables, and supported harness. Hooks can run when their configured events occur without the model requesting them. A marketplace listing doesn't establish that a hook's event format or commands are compatible with your session.

Follow the plugin installation steps , complete the publisher's setup, and verify the hook's execution in the intended environment. Check for duplicate hook sources before also adding a standalone copy. If execution differs from your expectations, follow hook troubleshooting . Find and manage hooks Select the harness before opening the hooks interface so the editor shows the relevant customization sources. Open the Chat view or Agents window.

Select Copilot from the Session Target UI control. Open the Agent Customizations editor: In the Chat view, select Open Customizations in the title bar, and then Hooks . In the Agents window, select Customizations in the sidebar, and then Hooks in the editor. In the Chat view, enter /hooks in the chat input. Select New Hook (plus icon) next to Workspace or User to create a hook, or select an existing hook to open its configuration.

To generate a hook with AI, describe the hook you want in chat. Review generated configuration and scripts against the destination reference before running them. Generation is not automatic migration or verification. Create your first Copilot hook Start with a diagnostic that records only the tool name, not its arguments or result. This example creates a workspace hook and requires Node.js on the execution host. For a hook you can use across repositories, follow Set up a personal hook .

Open your project folder and select Copilot from the Session Target control. Open the Agent Customizations editor and select the Hooks tab. Select New Hook (plus icon) next to Workspace . Select Pre-Tool Use . If existing hooks are listed, select Add new hook... . Select Create new hook config file... , choose the repository's .github/hooks folder if prompted, and enter audit as the file name. In the generated configuration, use the JSON below.

Complete the supporting script before testing the hook. The editor creates and opens the configuration file. Use the preToolUse event name in this example because the script expects the corresponding camelCase payload: { "version" : 1 , "hooks" : { "preToolUse" : [ { "type" : "command" , "command" : "node .github/hooks/log-tool-use.cjs" , "timeoutSec" : 10 } ] } } Next, add the supporting script at .github/hooks/log-tool-use.cjs .

The hook creation flow creates the configuration, not this script: const fs = require ( 'node:fs' ); const path = require ( 'node:path' ); const event = JSON . parse ( fs . readFileSync ( 0 , 'utf8' )); if ( typeof event . toolName !== 'string' ) { throw new Error ( 'Expected a Copilot preToolUse event with toolName.' ); } fs . appendFileSync ( path . join ( __dirname , 'tool-use.log' ), ` ${ JSON . stringify ( event . toolName ) } \n ` ); process . stdout . write ( '{}' ); Add .github/hooks/tool-use.log to .gitignore .

Start a new Copilot session and request a harmless task that uses a tool, such as reading a project file. Confirm that the log contains the tool name and that the task continues through its normal permission checks. Returning {} makes no permission decision; it does not automatically approve the tool. The log is written beside the script, so moving the script to your user hook directory keeps its log there too. For shared plugin hooks, use the bundled-script example ; do not write logs into an installed plugin's code directory.

After verification, remove tool-use.log . Keep its .gitignore entry if you continue using the diagnostic, or remove the diagnostic configuration and script if you no longer need them. Before sharing the hook, review the script, document its Node.js dependency, and repeat the check in each intended environment, such as a container or remote workspace. A successful local check does not confirm that the execution host has the same paths, dependencies, or permissions.

If you prefer to create the configuration directly, save the JSON as .github/hooks/audit.json , creating the folder if needed. Add the same supporting script and perform the verification above. Choose a hook source In the Agent Customizations editor, choose Workspace for shared repository hooks or User for personal hooks. The following table lists the underlying sources and other ways to distribute hooks: Need Source Personal automation across repositories User hook files in ~/.copilot/hooks/ , or $COPILOT_HOME/hooks/ when COPILOT_HOME is set.

Automation shared with a repository .github/hooks/*.json at the repository root Hooks alongside other personal or repository settings An inline hooks map in a supported Copilo

The rest of this page is on the live site.