Customize
Hooks
Run your own commands, HTTP calls, prompts or agents at fixed points of a KazoCode agent session, to block tool calls, add context, format code or send notifications.
Hooks run your own logic at fixed points in a session, every time, without relying on the model to remember. Use them to block risky commands, format files after each edit, add context to every prompt, or notify you when a task finishes.
Where hooks live
| File | Scope |
|---|---|
~/.kazocode/hooks.json | You, in every project |
.kazo/hooks.json | This project. KazoCode asks you to trust a project's hooks before running them |
A plugin's hooks/hooks.json | Wherever the plugin is on |
/hooks lists every hook that runs in the current workspace.
Example
Block force pushes, and format TypeScript after every edit:
{
"hooks": {
"PreToolUse": [
{
"matcher": "shell",
"hooks": [{ "type": "command", "command": "node .kazo/check-push.js" }]
}
],
"PostToolUse": [
{
"matcher": "edit_file|write_file",
"hooks": [{ "type": "command", "command": "pnpm prettier --write ." }]
}
]
}
}This is the same layout Claude Code uses, and Claude Code tool names in a matcher also match KazoCode's tools.
Events
| Event | Runs |
|---|---|
SessionStart | When a conversation starts |
UserPromptSubmit | When you send a message, before the agent sees it |
PreToolUse | Before a tool runs; can block it or change its input |
PermissionRequest | When the agent asks for approval; can allow or deny |
PostToolUse | After a tool succeeds |
PostToolUseFailure | After a tool fails |
Notification | When KazoCode would notify you |
SubagentStart, SubagentStop | When a sub-agent starts or finishes |
Stop | When the agent finishes its reply |
TaskCompleted, TeammateIdle | When a task in a team finishes or a teammate is idle |
PreCompact | Before a conversation is summarized |
WorktreeCreate, WorktreeRemove | When an agent worktree is made or removed |
ConfigChange | When settings, rules or servers change |
matcher is a tool name, a |-separated list, or a regular expression. Leave it out to match everything.
Hook types
type | Runs |
|---|---|
command | A shell command. The event arrives as JSON on standard input |
http | A POST of the event to a url, with optional headers |
prompt | A prompt for a model, which judges the event |
agent | A sub-agent that checks the event with tools |
What a hook can do
A command hook answers with its exit code and output:
- Exit 0: carry on. For
UserPromptSubmitandSessionStart, plain output is added as context for the agent. - Exit 2: block. The action is stopped and the hook's error output tells the agent why; for
PreToolUsethe tool call is denied. - Other exit codes: the hook failed. The session carries on and the failure is noted.
For finer control, print JSON: {"continue": false, "stopReason": "…"} stops the turn, and systemMessage adds a message for the agent.
Updated November 20, 2026