Claude Code hooks let you run your own commands at specific moments in an agent session: before a tool runs, after it finishes, or when the agent stops. They are the simplest way to add team automation around Claude Code, such as formatting, logging, guardrails or learning from changes, without changing how developers work. This guide explains how they work and shows examples.
What a hook is
A hook is a shell command that Claude Code runs when an event happens. The command receives details about the event as JSON on standard input, and can respond through its exit code and output. Hooks are configured in a settings file, so they can be shared with a project or kept personal.
The events you will use most
- PreToolUse: runs before a tool call, so you can inspect or block it.
- PostToolUse: runs after a tool call succeeds, useful for reacting to file edits.
- Stop: runs when the agent finishes responding, a natural point for summaries or checks.
A minimal configuration
Add a hooks section to your Claude Code settings. This example runs a script after any file edit:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "node scripts/after-edit.js" }
]
}
]
}
}The matcher selects which tools trigger the hook. Check the current Claude Code documentation for the exact schema, because it can evolve.
Practical examples
Auto-format after edits
Run your formatter on the files the agent changed so diffs stay clean.
Block risky commands
Use a PreToolUse hook on shell commands to reject patterns you never want an agent to run, such as force pushes to main.
Log what the agent did
Append each change to a local file for later review.
Turn each change into a lesson
When the agent stops, start a background job that explains what changed, so developers learn the code as it is written. That is exactly how Zevqi works: zevqi init installs hooks that record touched files, build a lesson after each turn without slowing the agent, and optionally warn before a commit when AI changes are not yet reviewed.
Best practices
- Never slow the agent. Do heavy work in a detached background process.
- Fail safe. A hook that crashes should not break the session. Exit cleanly unless you intend to block.
- Keep hooks idempotent. They may run many times in one session.
- Mind secrets. Hook input can include file paths and content. Do not log it carelessly.
- Test with a scratch repo before rolling out to the team.
Troubleshooting
- Hook not firing: confirm the settings file location and that Claude Code was restarted. Use the hooks view in Claude Code to see what is registered.
- Wrong tool matched: tighten the
matcherpattern. - Environment differences: hooks run in a shell that may lack your usual PATH.
Frequently asked questions
Are hooks safe?
They run commands on your machine, so only install hooks you trust and review shared settings files like any other code.
Can hooks change what the agent does?
Some events let a hook allow, block or provide feedback to the agent. See the official documentation for current capabilities.
Want to see hooks put to work? Read the Zevqi docs or try the team dashboard free for 7 days.
Neha Singh is the founder of Zevqi. She builds and tests the tools on this site and writes these guides from hands-on use. Follow on X (@heynehasingh) or read more about Zevqi.
Ready to put this into practice? Zevqi has the tools built in — free, no signup.