Text of code.claude.com › docs › en › plugins › mods › events as Styx crawled it on Nov 20, 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

React to events with a mod - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. A hook is an event handler: a function that Claude Code runs when a named event happens. Claude Code fires an event at each point where it’s about to act, such as when it runs a tool, submits a prompt, sends a request to the model, or starts or ends a session.

Your hook runs before Claude Code acts, so it can observe the event, rewrite it, or answer it in Claude Code’s place. You register a hook with on(eventName, handler) . Build your first mod before you start here. For every event and its exact fields, see the reference or read the types for your build . How a hook handles an event A hook sits between an event and what Claude Code would do about it, so it can observe the event, rewrite it, or answer it itself.

It receives three arguments: the mods API as $ , the event as e , and the next handler as next . The handlers for an event form a middleware chain. next(e) calls the next handler, which is another mod’s hook or, at the end of the chain, Claude Code’s own behavior, and it resolves to the result. What your hook does with next decides which of the three it does. Observe an event To observe an event without changing it, do your work and return next(e) .

This hook logs each tool Claude is about to use: on ( 'tool.call' , async ( $ , e , next ) => { // Runs before the tool does $ . ui . log ( 'Claude is about to use ' + e . tool ) // Pass the event on unchanged return next ( e ) }) Before each tool runs, a dim line such as ● my-mod: Claude is about to use Bash appears in the transcript, where my-mod is your plugin’s name. The tool runs as it would without the mod. To act after the event, await next(e) , do your work, and return the result.

This hook logs each tool after it has run: on ( 'tool.call' , async ( $ , e , next ) => { // Let the tool run, and wait for its result const result = await next ( e ) // Runs after the tool does $ . ui . log ( e . tool + ' finished' ) // Give the result back unchanged return result }) The line now appears after each tool finishes. Claude reads the same result either way, because the hook returns what next(e) resolved to.

Rewrite an event To change what Claude Code acts on, such as the text of a prompt, call next with a modified copy of the event. The event itself is immutable: it’s deeply frozen, and assigning to a field throws. This hook trims each prompt before it’s sent: on ( 'prompt.submit' , async ( $ , e , next ) => { // Pass on a copy of the event with its text changed return next ({ ... e , text: e . text . trim () }) }) Later handlers and Claude Code receive the trimmed prompt and never see the original.

You can also change the result: await next(e) , then return a copy of the result with a field replaced. Answer an event To handle an event yourself, return a result without calling next . That short-circuits the chain, so later mods and Claude Code’s own behavior don’t run. This hook refuses every Bash command: on ( 'tool.call' , { tool: 'Bash' }, async () => { // No call to next, so the command never runs return { deny: 'Bash is turned off in this project.

Use the file tools.' } }) When Claude tries a Bash command, the command doesn’t run, and Claude reads the deny text as the tool’s result. Each event has its own result shape, which the events reference lists. Filter which events a hook handles To run a hook for some events only, pass a filter as the second argument to on . Claude Code calls the filter a matcher. It’s an object whose fields are compared with the event’s, and the hook runs only when every field matches.

A field can be a value, an array of allowed values, or a regular expression. Each line in this example registers the same function, hook , for a narrower set of tool calls: // A string matches one value: Bash calls only on ( 'tool.call' , { tool: 'Bash' }, hook ) // An array matches any value in it: Edit calls and Write calls on ( 'tool.call' , { tool: [ 'Edit' , 'Write' ] }, hook ) // A regular expression matches by pattern: every tool of one MCP server on ( 'tool.call' , { tool: / ^ mcp__github__/ }, hook ) hook runs once for a Bash, Edit, or Write call, and once for a call to a tool whose name starts with mcp__github__ .

A call to any other tool, such as Read, matches none of the three, so hook doesn’t run for it. The event name can be a wildcard. 'classic.*' matches every settings hook event . '*' matches most events, but not the telemetry events , which take their own name and a { to: 'collector' } filter. Register each event once per matcher. If you call on twice for session.start with no matcher, the module fails to load with on("session.start") is registered twice without a matcher .

Put everything your mod does at session start in one hook. Hook other mods’ drawings and controls To hook another mod’s controls, panes, or row above the prompt, pass a matcher with plugin . Use the mod’s name without its marketplace, as in { plugin: 'other-mod' } , or { plugin: '*' } for every mod. Without plugin , a hook on ui.press , ui.input , ui.select , or ui.focus doesn’t run for other mods’ controls, and a ui.render hook skips their panes and their rows above the prompt.

A hook on a wildcard with no matcher, such as on('*', hook) or on('ui.*', hook) , still runs for every mod. A wildcard with a matcher needs plugin too. { plugin: '*' } requires Claude Code v2.1.323 or later. Before v2.1.323, a hook with no plugin ran for every mod, and a hook with { plugin: '*' } didn’t run. To match every mod on both versions, use { plugin: /./ } on ui.press , ui.input , and ui.select . For ui.focus and ui.render , use on('ui.*', hook) and check the event’s name in next.event , as in if (next.event !== 'ui.focus') return next(e) .

Hook what Claude is doing Handle these events to see or change a tool call, a prompt, a turn, or a settings read as it happens. For every event and what a hook can return, see the events reference . Guard or change a tool call A tool.call hook sees each tool Claude is about to use, so it can refuse the call, change its arguments, or let it through. tool.call fires when Claude Code is about to run a tool, including calls a subagent makes and calls to MCP tools. e.tool is the tool’s name and the tool’s arguments are fields of e , such as e.command for Bash.

When you call next(e) , Claude Code runs the permission check and then the tool. This hook refuses a Bash command that force-pushes, and tells Claude why: // The matcher limits the hook to Bash calls, so e.command is the shell command on ( 'tool.call' , { tool: 'Bash' }, async ( $ , e , next ) => { if ( /git push . * --force/ . test ( e . command )) { // Returning without calling next answers the event, so the command never runs return { deny: 'Force pushes are not allowed in this repository.

Push to a new branch instead.' } } // Every other command goes on to the permission check and then to Bash return next ( e ) }) When Claude tries git push --force , the command doesn’t run and no permission prompt appears, because the hook never calls next . Claude reads the deny text as the tool’s result, so write it as an instruction Claude can act on. Every other Bash command runs as it would without the mod. If this hook throws or times out, Claude Code skips it and the command goes on as it would without the mod.

To refuse the command instead, add a .catch handler to the hook. To act after a tool has run, await next(e) , do your work, and return what next gave you. This hook logs each .mdx file Claude changes, with $.ui.log , which adds a dim line to the transcript that Claude doesn’t read: on ( 'tool.call' , { tool: [ 'Edit' , 'Write' ] }, async ( $ , e , next ) => { // Wait for the permission check and the tool, and keep what they produced cons

The rest of this page is on the live site.