Hooks: running your own scripts around the agent

Hooks are your scripts, run by the agent at defined points. They are how you enforce something mechanically rather than asking the model to remember it.

Where they live

.toolsxpo/hooks/    in your repository
~/.toolsxpo/hooks/  on your machine

Enable them under Settings → Editor → Hooks. The setting is on by default, but it does nothing until you have written a hook — there is nothing to run.

What they are good for

Formatting after edits. Run your formatter on the changed file so the agent never has to think about style, and never burns a turn fixing it.

Blocking dangerous commands. A hook that inspects a command before it runs can refuse rm -rf, a production deploy, or anything touching a path you care about. A rule asks the model not to; a hook makes it impossible.

Logging. Record what the agent did, for review or audit.

Why a hook beats a rule for enforcement

A rule is advice to a language model. It is followed most of the time.

A hook is code. It runs every time, regardless of what the model intended. For anything where "most of the time" is not good enough, use a hook.

They execute arbitrary code

Hooks run with your permissions. Treat a hook file the way you would treat any script in your repository — review it before enabling, especially in a project you did not write.

This is why hooks do nothing until you create one, and why the setting is worth knowing about even though it is on by default.

See also

• Rules
• Terminal and commands