Claude Code Hooks That Format, Lint and Test After Every Edit

Where hooks live

Hooks go in a settings file. .claude/settings.json is committed, so your whole team gets them. .claude/settings.local.json is just for you. Each hook has three levels: the event, a matcher that picks which tools it applies to, and the command to run.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format-and-test.sh",
            "timeout": 120
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/lint-before-stop.sh",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Claude Code passes each hook a JSON object on stdin: the session, the event, and for tool events the tool's name and input. The scripts below read it with jq, so install that first: brew install jq on a Mac. CLAUDE_PROJECT_DIR is the folder the session started in, so the scripts work from any subfolder.

The edit hook: format, lint, related tests

Save this as .claude/hooks/format-and-test.sh and run chmod +x .claude/hooks/*.sh:

#!/bin/bash
# PostToolUse on Edit|Write: format the file, lint it,
# then run only the tests that import it.
# Exit 2 sends stderr back to Claude. The edit itself is already on disk.
INPUT=$(cat)
FILE=$(jq -r '.tool_input.file_path // empty' <<<"$INPUT")
[[ -z "$FILE" || ! -f "$FILE" ]] && exit 0
case "$FILE" in
  *.ts|*.tsx|*.js|*.jsx|*.mjs) ;;
  *) exit 0 ;;
esac
cd "$CLAUDE_PROJECT_DIR" || exit 0

npx prettier --write --log-level warn "$FILE" >/dev/null 2>&1

if ! LINT=$(npx eslint --no-warn-ignored "$FILE" 2>&1); then
  echo "ESLint failed on $FILE. Fix these before moving on:" >&2
  echo "$LINT" | tail -30 >&2
  exit 2
fi

if ! TESTS=$(npx vitest related "$FILE" --run --passWithNoTests 2>&1); then
  echo "Tests that cover $FILE are failing:" >&2
  echo "$TESTS" | grep -v '^\s*$' | tail -30 >&2
  exit 2
fi
exit 0

It takes the edited file's path from tool_input.file_path, skips anything that is not code, and then runs three checks in order:

1. Prettier rewrites the file. No output, because formatting is never Claude's problem to fix.
2. ESLint on that one file. If it fails, the errors go back to Claude.
3. Vitest related runs only the test files that import the edited file, not the whole suite. If one fails, the failure goes back to Claude.

On this repo the whole hook took 2.4 to 4.1 seconds per edit, most of it npx starting three tools. In the first test run it caught both problems I planted. Claude wrote a file with a word in a string that a custom lint rule in this repo bans from site copy, and the hook blocked with the rule's message. Claude then wrote a test for a slugify that only replaced the first space, and the hook blocked with the failing assertion. Claude fixed both without being asked, using replaceAll and the word the rule asks for.

Tell Claude when it passed

The first version of the hook printed nothing on success. At the end of that run, Claude reported: "The hooks printed nothing after the fix, which probably means they passed, but I didn't run the test to confirm." To Claude, silence means it doesn't know. So say it out loud. Replace the last exit 0 with:

SUMMARY=$(echo "$TESTS" | grep -E '^\s*Tests ' | sed 's/^ *//' | head -1)
MSG="Hook: formatted with Prettier, ESLint clean,"
MSG="$MSG related tests: ${SUMMARY:-none found}."
jq -nc --arg msg "$MSG" \
  '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'
exit 0

additionalContext reaches Claude as a note next to the tool result. In the second run, Claude quoted it back after each step: "formatted with Prettier, ESLint clean, related tests: Tests 1 passed (1)".

A Stop hook for what the edit hook misses

The edit hook only fires on Claude's Edit and Write tools. A file Claude creates through the shell, with printf, sed or a heredoc, never triggers it. In the third run I asked Claude to do exactly that, and the edit hook stayed silent.

A Stop hook runs when Claude is about to end its turn. This one lints every TypeScript file that differs from the last commit, plus new untracked ones, however they got there:

#!/bin/bash
# Stop: refuse to end the turn while a changed TypeScript file fails lint.
INPUT=$(cat)
# Already continuing because of a Stop hook: let Claude stop this time.
[[ "$(jq -r '.stop_hook_active' <<<"$INPUT")" == "true" ]] && exit 0
cd "$CLAUDE_PROJECT_DIR" || exit 0
FILES=$( { git diff --name-only --diff-filter=ACMR HEAD -- '*.ts' '*.tsx';
           git ls-files --others --exclude-standard -- '*.ts' '*.tsx'; } | sort -u )
[[ -z "$FILES" ]] && exit 0
if ! OUT=$(npx eslint --no-warn-ignored $FILES 2>&1); then
  echo "Lint still fails on files you changed. Fix it before you finish:" >&2
  echo "$OUT" | tail -30 >&2
  exit 2
fi
exit 0

In the third run it found the shell-written file, blocked the finish with ESLint's message, and Claude fixed the file and tried to stop again. Exit 2 on a Stop hook means "keep going", and the stderr text becomes Claude's next instruction.

Keep the Stop hook from looping

A Stop hook that blocks on something Claude cannot fix would block forever. Claude Code passes stop_hook_active: true when Claude is already continuing because of a Stop hook. The script's first check lets Claude stop in that case, which is why the second stop in run three took 17 milliseconds.

Claude Code also has its own cap: after Stop hooks continue the turn eight times in a row, it overrides the next block and ends the turn. The count resets every time Claude calls a tool.

Test it headless before you trust it

Before committing the hooks, run a throwaway session that is designed to trip them. Point --settings at the file, write a debug log, and give Claude a task with a planted bug:

claude -p --settings .claude/settings.json --permission-mode acceptEdits \
  --debug-file /tmp/hooks.log --output-format json \
  "Create src/lib/hooktest/slug.ts exporting
   slugify = (s: string) => s.toLowerCase().replace(' ', '-'),
   then a vitest test expecting slugify('Hello Big World')
   to be 'hello-big-world'. Fix only what a hook reports.
   Finish with one line saying what the hooks told you."

grep "Hooks: " /tmp/hooks.log
# PostToolUse:Write [.../format-and-test.sh] finished with status 2 (2450ms)
# PostToolUse:Edit [.../format-and-test.sh] finished with status 0 (4072ms)
# Stop [.../lint-before-stop.sh] finished with status 0 (1527ms)

Status 2 means the hook blocked and Claude got the message. Then delete the test folder. These are the three runs I made:

Usage is the cost Claude Code reported for each headless run. On a Pro or Max plan it counts against your plan's limits rather than a bill.