Skip to content
igardev edited this page Sep 28, 2026 · 4 revisions

Hooks

Overview

Hooks are actions that execute in response to specific events during the agent's workflow. For example, you can run hooks before or after a tool execution (preToolUse and postToolUse).

How It Works

Define a folder for hooks using the hooks_folder setting, then place one or more .json files inside that folder. Each hook file contains hooks grouped by event type. Every hook consists of two fields:

  • matcher: A regular expression pattern that determines which tool calls the hook applies to.
  • script: The command(s) to execute, written in the llama-vscode scripting language. This can either be an inline script or an absolute path to an external script file (e.g., .lvs).

Example

Here is an example hooks.json file:

{
    "version": 1,
    "hooks": {
        "preToolUse": [
            {
                "matcher": "edit_file",
                "script": "/path/to/logToolCall.lvs"
            }
        ],
        "postToolUse": [
            {
                "matcher": "edit_file",
                "script": "runTerminalCommand test -s '$file_path' && sha256sum '$file_path' >> /path/to/audit.log "
            }
        ]
    }
}

Available Events

Event Description
preToolUse Executed before a tool is called.
postToolUse Executed after a tool has completed.
userPromptSubmit Executed before the prompt is submitted to the agent. Could prevent submitting the prompt if the return value starts with "stop loop"
stop Executed after the agent loop has completed. Could prevent stopping the agent if the return value starts with "continue" (the complete return value is sent to the agent so that it knows how to continue).

Available Variables

Variable Description
$eventName The name of the event.
$toolName The name of the tool (if applicable).
$file_path The path to the file - for tools edit_file, read_file, multi_edit_file
$prompt The submitted prompt - for userPromptSubmit event

Settings

Setting Description
hooks_folder The directory where hook files (.json) are stored. You can place multiple hook files in this folder; each file may define any number of hooks.

Notes

  • The matcher field uses regular expressions, so you can match multiple tools (e.g., edit_file|write_file matches both).
  • Inline scripts support variables and functions from the llama-vscode scripting language. Use $variableName syntax to reference variables.
  • External script files (e.g., .lvs) must be located relative to the hooks_folder.
  • If a preToolUse hook script returns a string, which starts with "stop", the tool will not be called.

Clone this wiki locally