Claude Code hooks, tested: five scripts you can copy
Five small Claude Code hooks with a test script: protect files, block risky commands, format after edits, check before stopping, and log every command.
At a glanceSet up a repository for Claude Code with four files: CLAUDE.md, .claude/settings.json, one hook and .mcp.json. What belongs in each, with documented examples.
Not testedWritten from Anthropic's documentation. Commands were checked against the built-in help; the hook examples were not run.
Claude Code runs in any folder with no setup. On a real project, four small files decide how well it behaves: one for instructions, one for permissions, one script for the rule that must never break, and one for outside tools. Each takes a few minutes, and all four can be committed so the whole team gets the same behaviour.
Claude Code starts each session with a fresh context and reads CLAUDE.md first. The documentation lists three places that matter for most people:
./CLAUDE.md or ./.claude/CLAUDE.md for the project, shared through version control.~/.claude/CLAUDE.md for your own preferences in every project../CLAUDE.local.md for private notes on one project. Add it to .gitignore yourself.Run /init inside Claude Code to generate a first version. It reads the codebase and writes down the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, it suggests improvements and does not overwrite the file.
Then cut it down. The documentation's target is under 200 lines per file, because longer files use more context and are followed less reliably. Keep what Claude cannot work out from the code: the exact test command, the branch naming rule, the directory nobody should touch. Rules that apply to one part of the codebase can move to .claude/rules/, where a rule can be scoped to file paths and loads only when Claude works on matching files.
The documentation is direct about the limit of this file. Claude treats CLAUDE.md as context, not as enforced configuration. A line that says "never edit the lockfile" is a request. To make it a guarantee, use a permission rule or a hook, which the next two sections cover.
If the repository already has an AGENTS.md for other coding agents, Claude Code can read that file in place of CLAUDE.md.
Settings are JSON files, and the file you choose decides who the setting applies to:
| File | Applies to | Commit it? |
|---|---|---|
~/.claude/settings.json | You, in every project | No |
.claude/settings.json | Everyone working in the project | Yes |
.claude/settings.local.json | You, in this project only | No |
When the same key is set in more than one file, the local file wins over the shared project file, which wins over your user file. Settings deployed by an organization sit above all three. Lists such as permissions.allow are merged across files, so each file can add entries without removing another file's.
The documentation's own example lets Claude run lint and tests without asking, and stops it reading .env files:
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)"
]
}
}
Three details save time later:
/status to see which settings files loaded, and claude doctor to list entries that were rejected.allow rules apply only after each teammate trusts the folder. deny and ask rules apply immediately.When you choose "Yes, and don't ask again" on a permission prompt, Claude Code saves that approval to .claude/settings.local.json and keeps the file out of git. How the three rule types interact is covered in Claude Code permission settings order.
A hook is a shell command that Claude Code runs at a fixed point, such as before a tool call. Because it is a command and not an instruction, it runs every time. Hooks are configured in the same settings files.
The documentation's example blocks edits to sensitive files. Save this as .claude/hooks/protect-files.sh and make it executable with chmod +x. It needs jq installed.
#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")
for pattern in "${PROTECTED_PATTERNS[@]}"; do
if [[ "$FILE_PATH" == *"$pattern"* ]]; then
echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
exit 2
fi
done
exit 0
Then register it in .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
}
]
}
]
}
}
Claude Code passes the details of the tool call to the script as JSON on standard input. Exit code 2 blocks the call, and the message written to standard error goes back to Claude as feedback, so it can change approach. Exit code 0 makes no decision, and the normal permission flow applies.
The same structure with PostToolUse runs a command after an edit, which is how the documentation formats files with Prettier. Type /hooks in a session to see what is registered.
A hook is an ordinary command running on your machine. Read the hooks in a repository you did not write before you trust the folder.
MCP servers give Claude Code access to tools outside the repository, such as an issue tracker or an error monitor. The built-in help of version 2.1.322 gives these two forms:
# A remote server over HTTP
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
# A local server started as a command
claude mcp add my-server -e API_KEY=xxx -- npx my-mcp-server
By default a server is added in the local scope: only you, only this project. Add --scope project to write it to .mcp.json in the project root, which you can commit, or --scope user to have it in all your projects.
A committed .mcp.json looks like this:
{
"mcpServers": {
"shared-server": {
"type": "http",
"url": "https://example.com/mcp"
}
}
}
Keep secrets out of the file. Values can be written as ${VAR}, or ${VAR:-default} with a fallback, and are filled in from each person's environment.
Claude Code asks for approval before it uses a server from a project's .mcp.json in an interactive session. claude mcp list, claude mcp get <name> and claude mcp remove <name> manage servers from the terminal, and /mcp shows their status inside a session. The documentation adds a warning worth repeating: verify that you trust each server, because one that fetches outside content can expose you to prompt injection.
| File | Commit | Holds |
|---|---|---|
CLAUDE.md | Yes | Project instructions |
.claude/settings.json | Yes | Team permissions and hooks |
.claude/hooks/ | Yes | The scripts your hooks call |
.mcp.json | Yes | Shared servers, without secrets |
.claude/settings.local.json | No | Your overrides and saved approvals |
CLAUDE.local.md | No | Private notes |
A workable order for a new repository: run /init and trim the result, add deny rules for secrets, write one hook for the rule you care about most, and add MCP servers when a task needs them. If Claude Code is not installed yet, start with installation and first login.
This article reflects public information available when it was written. Versions, defaults and prices can change; check the linked official documentation.
The file locations and examples follow Anthropic's documentation as read on November 12, 2026. The MCP commands were checked against the built-in help of Claude Code 2.1.322; the hook examples were not run for this article. Written for this site with AI assistance, from the sources above. For errors or additional information, please request a correction. Editorial policy
Found this useful? Share it, or follow for new guides.