KazoCode DocsAccount

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.

On this page

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

FileScope
~/.kazocode/hooks.jsonYou, in every project
.kazo/hooks.jsonThis project. KazoCode asks you to trust a project's hooks before running them
A plugin's hooks/hooks.jsonWherever the plugin is on

/hooks lists every hook that runs in the current workspace.

Example

Block force pushes, and format TypeScript after every edit:

.kazo/hooks.json
{
  "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

EventRuns
SessionStartWhen a conversation starts
UserPromptSubmitWhen you send a message, before the agent sees it
PreToolUseBefore a tool runs; can block it or change its input
PermissionRequestWhen the agent asks for approval; can allow or deny
PostToolUseAfter a tool succeeds
PostToolUseFailureAfter a tool fails
NotificationWhen KazoCode would notify you
SubagentStart, SubagentStopWhen a sub-agent starts or finishes
StopWhen the agent finishes its reply
TaskCompleted, TeammateIdleWhen a task in a team finishes or a teammate is idle
PreCompactBefore a conversation is summarized
WorktreeCreate, WorktreeRemoveWhen an agent worktree is made or removed
ConfigChangeWhen 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

typeRuns
commandA shell command. The event arrives as JSON on standard input
httpA POST of the event to a url, with optional headers
promptA prompt for a model, which judges the event
agentA 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 UserPromptSubmit and SessionStart, 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 PreToolUse the 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