Hooks — Automation That Runs Itself
set up automated actions that trigger before, during, and after Claude Code sessions. After this module, your setup will back itself up automatically, catch dangerous operations before they happen, and validate your work as you go.
What Hooks Do
Every module so far has been about things you actively do — write a CLAUDE.md, create a skill, run a command. Hooks are different. Hooks are things that happen without you doing anything.
A hook is a small script that runs automatically when something specific happens in Claude Code. "When a session starts, do this." "Before Claude runs a terminal command, check this." "When a session ends, do that."
You set them up once. They run forever after. You don't invoke them, you don't think about them, you don't even notice them — until the day they save you from a mistake.
The Three Hooks That Matter
There are many things you could automate with hooks. We're going to set up three. These three handle the most common failure modes: losing your work, running something dangerous, and shipping broken code.
Hook 1: Auto-Backup (git-sync)
What it does: Every time you start or end a Claude Code session, this hook automatically saves your .claude/ configuration to a backup. Your CLAUDE.md, skills, commands, settings — everything you've built in this guide gets backed up automatically.
Why it matters: You've spent real time building this setup. Without a backup, one bad edit to your CLAUDE.md or an accidental file deletion means starting over. This hook means you never lose your configuration.
How it works:
First, let's set up the backup system. We're using git — a version control tool that tracks changes to files. If you've never used git, that's fine. We'll set it up once and the hook handles everything after that.
Step 1: Initialise git in your .claude folder
This tells git to start tracking changes in your .claude/ directory.
Step 2: Create a .gitignore file
Some things in .claude/ don't need backing up — temporary files, caches, downloaded plugins. Let's tell git to ignore them.
Create a file called .gitignore in ~/.claude/:
Step 3: Make your first commit
This saves the current state of everything. Think of it as a snapshot.
Step 4: Create the hook script
Create the directory for hook scripts:
Create ~/.claude/scripts/hooks/git-sync.sh:
Make it executable:
Step 5: Register the hook in Claude Code settings
Open ~/.claude/settings.json (create it if it doesn't exist) and add the hooks configuration. If the file already has content, you'll need to add the hooks section to the existing JSON. Here's what the hooks section looks like:
The "matcher": "" means "run this for all events" (for session hooks, there's nothing to match against — the hook just fires). The "type": "command" tells Claude Code this is a shell command to execute.
That's it. From now on, every time you start or end a Claude Code session, your configuration is automatically backed up. You'll never think about it, and you'll never lose your setup.
Optional but recommended: If you have a GitHub account, you can push these backups to GitHub for offsite storage. Create a private repository and add it as a remote:
Then update the hook script to also push:
The & at the end means the push happens in the background — it doesn't slow down your session start.
Hook 2: Safety Gate
What it does: Before Claude Code runs any terminal command, this hook checks whether the command is potentially destructive. If it is, the hook blocks it and warns you.
Why it matters: Claude Code can run commands on your computer. Most of the time, this is exactly what you want — it's what makes Claude Code powerful. But occasionally, a misunderstood instruction could lead to a command that deletes files you need, modifies system settings, or does something you didn't intend. The safety gate catches these before they execute.
What it catches:
The hook blocks commands that are almost never what you want:
rm -rfon system directories (home folder, root, system paths)- Disk formatting commands (
mkfs,dd) - Fork bombs and resource exhaustion
- Commands that exfiltrate credentials or sensitive files
It deliberately doesn't block things that are sometimes dangerous but often legitimate — like force-pushing to git or running destructive database queries. Those require judgement, not blanket blocking. Claude's own safety checks handle those.
Create the script:
Create ~/.claude/scripts/hooks/safety-gate.sh:
Make it executable:
Register it in settings.json:
Add to the hooks section (alongside the SessionStart and SessionEnd hooks you already have):
The "matcher": "Bash" means this hook only runs when Claude is about to execute a terminal command — not when it reads files or edits text.
Token cost: Zero. Hooks run outside of the Claude conversation. They don't consume any of your tokens.
Hook 3: Type Checking (for developers)
What it does: After Claude edits or creates a TypeScript file, this hook automatically runs the TypeScript compiler to check for errors. If Claude introduced a type error, you'll know immediately.
Why it matters: Claude is good at writing code, but it occasionally introduces type errors — especially when working with complex codebases. Without this hook, you might not discover the error until you try to build the project, several steps later. Catching it immediately saves the debugging round-trip.
Who needs this: Only developers working with TypeScript. If you don't write code, skip this hook entirely.
Create the script:
Create ~/.claude/scripts/hooks/tsc-check.sh:
Make it executable and register it:
This runs after any file edit or creation. If the project has TypeScript, it checks. If not, it does nothing.
How Hooks Work (The Mental Model)
Now that you've set up the hooks, let's solidify the understanding.
Claude Code has four hook points — moments where it pauses and runs your scripts:
| Hook Point | When It Fires | Use Case | |-----------|--------------|----------| | SessionStart | When you launch Claude Code | Setup, sync, loading context | | SessionEnd | When you close a session | Backup, cleanup, logging | | PreToolUse | Before Claude takes an action | Safety checks, validation | | PostToolUse | After Claude completes an action | Verification, quality checks |
The matcher field lets you filter which actions trigger the hook. "Bash" means only terminal commands. "Edit|Write" means only file modifications. You can be as specific or broad as you need.
Each hook script receives context about what's happening (the command being run, the file being edited) and can either allow it, block it, or add information to the conversation.
A Note for Windows Users
The hook scripts above are written in bash, which works on Mac and Linux. On Windows, you have two options:
- Use WSL (Windows Subsystem for Linux). If you're running Claude Code through WSL, the bash scripts work as-is. This is the recommended approach.
- Rewrite as PowerShell scripts. The logic is the same — only the syntax changes. Ask Claude Code to convert any bash hook script to PowerShell, and it'll handle the translation.
If you're on Windows and something isn't working, the shell script is almost always the reason. Check that your scripts match your shell.
What We Didn't Automate (And Why)
Hooks can do a lot more than what we've set up. You could automate testing, linting, deployment, notifications — anything a shell script can do. But each hook adds complexity and potential failure points.
We chose three hooks because they cover the three highest-impact automation needs:
- Don't lose your work (git-sync)
- Don't break your computer (safety-gate)
- Don't ship broken code (tsc-check)
Everything else is optional complexity. If you find yourself manually doing something at the start or end of every session, that's a candidate for a hook. But start with these three and add more only when you feel a specific need.
Your setup now runs on autopilot in the background. Configuration is backed up automatically. Dangerous commands are caught before they run. Code quality is checked as you work. None of this costs tokens. None of it requires your attention. It just works.
Next: the memory system. Making Claude remember things across sessions — not just preferences, but actual knowledge about you and your work.