Use Claude Code Hooks to Keep Your Code Clean Automatically

You ask Claude to build something. It does. The file gets written, Claude reports back — and you realize the code was never formatted. The tests were never run. Nothing broke, but you don't actually know that yet.

You could add "and run prettier and pytest when you're done" to every prompt. Or you set up two hooks once and forget about it forever.

---

Why Claude Never Remembers to Run Your Formatter

Claude works from your prompt, not your habits. If "run black after editing" isn't in your instructions, it won't happen. You can put it in your system prompt, but that's just hoping Claude reads it correctly every time.

Hooks are different. They're not instructions to Claude — they're shell commands that run automatically when specific events fire. Claude's judgment is not involved. The event fires, the command runs. That's it.

If you're new to hooks, read What Are Claude Code Hooks? first — this guide assumes you know what they are and focuses on the specific setup for code quality.

---

Two Hooks That Handle Code Quality

Claude Code supports several hook events, but for keeping code clean, two cover everything:

• PostToolUse — fires after Claude uses a tool (like writing a file)
• Stop — fires when the main Claude session ends

That's the full setup. You don't need the others for this use case.

PostToolUse — Clean Up After Every File Write

PostToolUse fires after every tool use. With a matcher: "Write" filter, it only triggers when Claude writes a file. This is where you put your formatter.

The hook runs synchronously — Claude waits for it to finish before moving on. That's exactly what you want for formatting: the file is cleaned up before Claude continues. It's also why you don't want to run a full test suite here. Slow hooks slow Claude down. Keep PostToolUse fast.

What makes this powerful: the stdin payload includes tool_input.file_path — the exact path of the file Claude just wrote. Your hook can format only that file instead of the whole project.

Stop — Validate the Whole Session

Stop fires when the main Claude session ends — after Claude has finished everything and is about to report back to you.

This is where you run heavier validation: your full test suite, TypeScript type checking, a build step. By the time Claude's summary appears in your terminal, those checks have already run. If something is broken, you know before you've even read the response.

One thing to be clear on: Stop fires for the main session. If you're using subagents (parallel Claude workers), those fire SubagentStop instead — a separate event. If you're not sure whether you're using subagents, you probably aren't. See What Are Claude Code Agents? for the distinction.

---

Setting Up a PostToolUse Formatter Hook

Here's a working PostToolUse hook that runs Prettier on the file Claude just wrote. Add this to .claude/settings.json in your project root:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$(jq -r '.tool_input.file_path' < /dev/stdin)\""
          }
        ]
      }
    ]
  }
}

The jq call reads the file path from the stdin JSON payload. jq is not bundled with Claude Code — you need to install it separately (e.g., brew install jq on Mac, winget install jqlang.jq on Windows, or your distro's package manager on Linux). If you'd rather not install it, replace the command with a Node.js one-liner that works on all platforms without any extra dependencies:

node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>require('child_process').execSync('npx prettier --write \"'+JSON.parse(d).tool_input.file_path+'\"',{stdio:'inherit'}))"

Windows note: The jq ... < /dev/stdin syntax requires a Unix shell (bash, zsh, or WSL). Native Windows environments (cmd/PowerShell) need the Node.js form above.

For Python projects, swap the command for:

black "$(jq -r '.tool_input.file_path' < /dev/stdin)"

Or if you prefer ruff:

ruff format "$(jq -r '.tool_input.file_path' < /dev/stdin)"

These also require jq and a Unix shell. On Windows (without WSL), use the Node.js form, replacing npx prettier --write with black or ruff format as the command to execute.

The rest of the hook structure stays identical.

---

Setting Up a Stop Hook for Tests and Type Checks

Stop hooks don't receive a file path — they fire at the end of the whole session. Run whole-project commands here.

For a JS/TS project:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx tsc --noEmit && npm test"
          }
        ]
      }
    ]
  }
}

For a Python project:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "pytest"
          }
        ]
      }
    ]
  }
}

Note there's no matcher on Stop hooks — Stop is a session-level event, not a tool event, so there's nothing to match against. If you add a matcher field anyway, it is silently ignored.

---

Running Both Together

PostToolUse and Stop are additive. You can have both configured at the same time — they don't conflict.

The workflow becomes:

1. Claude writes a file → PostToolUse fires → formatter runs on that file instantly
2. Claude finishes the session → Stop fires → type check and test suite run
3. Claude's response appears in your terminal

Per-file issues get caught immediately. End-to-end breakage gets caught before you read the summary. You didn't type a single extra command.

---

What Happens When a Hook Fails

Exit codes control what Claude does when a hook fails:

| Exit code | What happens | |---|---| | 0 | Success — Claude continues normally | | 2 | Blocking error — stderr is fed back to Claude as an error message. On Stop this prevents Claude from stopping; on PostToolUse the tool has already run, so it surfaces the error without undoing the write | | Any other non-zero | Non-blocking — stderr is shown in verbose mode only, execution continues |

This distinction matters for how you configure each hook.

Formatters (PostToolUse): Let failures pass silently. If Prettier chokes on a file, you don't want Claude to stop the whole session. Set your formatter to exit 0 on failure, or use || true at the end of the command:

npx prettier --write "$FILE" || true

Test gates (Stop): Surface the failure. If your tests break, you want Claude to know. Let pytest or npm test exit with their natural exit code. If that's non-zero, use exit 2 in a wrapper script to make Claude treat it as a hard failure:

pytest || exit 2

When exit code 2 is used, Claude receives your command's stderr output as the error message — not stdout. Write to stderr in your wrapper scripts, and Claude (and you) will know exactly what failed.

---

Starter Config for a JS/TS Project

Drop this into .claude/settings.json at your project root. Formats on every file write, type-checks and tests at session end.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            // Run Prettier on the file Claude just wrote
            "command": "npx prettier --write \"$(jq -r '.tool_input.file_path' < /dev/stdin)\" || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            // Type-check the whole project, then run tests. Fail hard on either.
            "command": "npx tsc --noEmit && npm test || exit 2"
          }
        ]
      }
    ]
  }
}

Important: The // comment lines above are for illustration only — standard JSON does not support comments, and .claude/settings.json is parsed as strict JSON. Remove all comment lines before saving the file or it will fail to parse.

---

Starter Config for a Python Project

Same structure, Python tooling. Uses ruff format for speed — swap for black if you prefer it.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "ruff format \"$(jq -r '.tool_input.file_path' < /dev/stdin)\" || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "pytest || exit 2"
          }
        ]
      }
    ]
  }
}

ruff format handles formatting (indentation, line wrapping — equivalent to Black). ruff check --fix is a separate subcommand for lint-related fixes like removing unused imports. If you want both, add a second command in the Stop array: ruff check --fix . && ruff format ..

---

These two hooks — one PostToolUse, one Stop — are the entire code quality setup. Five minutes to configure, and you never think about formatters or forgotten test runs again.

If you haven't set up Claude Code yet, start with the guide for Windows or Mac. Once it's running, explore Skills — the companion feature for shaping how Claude writes code in the first place.