Repository navigation
Hooks
igardev edited this page Sep 28, 2026
·
4 revisions
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).
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).
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 "
}
]
}
}| 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). |
| 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 |
| 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. |
- The
matcherfield uses regular expressions, so you can match multiple tools (e.g.,edit_file|write_filematches both). - Inline scripts support variables and functions from the llama-vscode scripting language. Use
$variableNamesyntax to reference variables. - External script files (e.g.,
.lvs) must be located relative to thehooks_folder. - If a preToolUse hook script returns a string, which starts with "stop", the tool will not be called.