Download free

Hooks

Make a command or a function of yours run at each moment of the agent's work: before a tool, when you send a message, when it finishes.

Updated · version 2.0.145 · Markdown

A hook is something of yours that runs by itself at a moment of the agent's work: before it uses a tool, when you send a message, when a turn ends. It can let the step through, block it, ask you for permission or add context.

Where hooks come from

  • From a project: the file .osiris/hooks.json in the project's folder.
  • From a plugin you have turned on.
  • From another agent: you bring them in from «Settings» › «Import», and they arrive turned off. See Import from other agents.

The first time a project brings hooks, the app asks you before it runs anything: the card says that the project, by its name, wants to run its own automatic steps on your Mac while you work in it, and lists those commands. If they change later, it asks again and they do not run until you approve the change. The same card lists what the project's settings files (.claude/settings.json and .claude/settings.local.json, in the folder and the folders above it up to the repository) let run or open without asking: those rules apply only after your yes for that folder, and a rule added later waits for your approval. What those files refuse or ask about always holds.

A command hook

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "shell",
        "hooks": [{ "type": "command", "command": "python3 hooks/guard.py" }]
      }
    ]
  }
}

The command gets the event as JSON on standard input. If it exits with code 2, it blocks the action and its message reaches the agent.

The moments used most:

EventWhen it runs
SessionStartWhen a chat starts.
SetupRight after the app makes a new working copy (a git worktree) for a chat or a helper: use it to install what the copy needs. It gets the folder of the copy and the folder it was made from. If it fails, the copy is still made and you are told.
UserPromptSubmitWhen you send a message.
PreToolUseBefore the agent uses a tool. It can block it.
PostToolUseAfter it uses it.
StopWhen the agent ends its turn.
PreCompactBefore the conversation is compacted.

A function hook

A function hook is JavaScript that runs inside the app, with no process to start. It takes the same decision as a command hook in a fraction of the time.

  1. In your hooks file, use the type function and name the file:
{ "type": "function", "file": "hooks/guard.js" }
  1. Write the function. It gets the event and returns its decision:
export default function (input) {
  const command = (input.tool_input || {}).command || "";
  if (command.startsWith("rm ")) {
    return { decision: "deny", reason: "This project deletes nothing from a command." };
  }
}

What it may return:

FieldWhat it is for
decisionallow, deny or block.
reasonThe why, which the agent reads.
updatedInputThe tool's input, corrected.
additionalContextText added to what the agent knows.

If it returns nothing, the work goes on.

What a function hook cannot do

  • It sees none of your files, the network or other programs: it runs isolated, with the language alone.
  • It can read text inside the project with ctx.readFile. It reaches the network only if the hooks file says "network": true.
  • It has 50 ms of processor time per call (set it with timeout, from 5 ms to 5 s). If it runs over, it is stopped and decides nothing.
  • An error of its own never breaks the turn: you see one line with the error and the work goes on.

When a hook stops something

MessageWhat happened
«One of your hooks did not let this message through: …»A UserPromptSubmit hook blocked it.
«One of your hooks stopped this turn: …»A hook asked to stop.
«One of your hooks did not let the context be compacted: …»A PreCompact hook blocked it.