←Back/Engineering/Claude Code
AdvancedEngineering

Automate Code Quality and Fixes with AI Stop Hooks

Use an agent stop hook to run project-specific checks when files change, feed actionable failures back into the same session, and finish only when the bounded validation loop passes.

Try this with your AI assistant

Download the skill for this workflow. Version 1.0.1.

Download skill
Automate Code Quality and Fixes with AI Stop Hooks
Source episode · 27:00Beyond Vibe Coding: Advanced AI Engineering with John Lindquist

with Claire Vo

John configures a Claude Code stop hook that detects changed files, runs a Bun type check, sends structured error output back to Claude, and commits only after the checks pass.

Read the full episodeWatch on YouTubeListen on SpotifyListen on Apple

Before you start

What you need

  • A repository with deterministic quality commands
  • Claude Code project settings
  • A hook script and runtime
  • A policy for which files the hook may inspect and commit

What you’ll make

A bounded post-task loop that catches relevant defects, returns clean diagnostics to the agent, and records a validated change without touching unrelated work.

Tools used

The workflow

Follow the sequence once, then adapt the prompts, checks, and handoffs to your own setup.

5 steps

Step 01

Create a Stop Hook Script

Create a project-local hook script and read Claude’s stop-hook input from standard input. Track the session, current directory, changed files, and retry count without writing secrets to logs.

Step 02

Implement Quality Checks in the Script

If no relevant files changed, exit cleanly. Otherwise map the changed paths to focused commands such as typecheck, lint, tests, formatting, dependency checks, or document validation.

Step 03

Handle Check Failures Automatically

When a check fails, emit one valid JSON response that names the command, exit status, affected files, and concise diagnostic output. Reserve standard output for that response.

Example prompt
Fix the reported validation failures without changing unrelated files. Rerun the failing command, explain any remaining error, and stop after [maximum attempts] rather than repeating the same edit.
Step 04

Handle Check Successes

When checks pass, inspect the exact task diff and sensitive-file rules. If automatic commits are allowed, stage only the task-owned files and generate a conventional commit message; otherwise leave the validated diff uncommitted with a summary.

Example prompt
Role: You are an expert programmer who writes git commit messages in the conventional commit format.

Task: Generate a git commit message for the following code changes.

Diff:
[paste git diff]

Output only the commit message.
Step 05

Configure the Hook in Settings

Register the script as a project stop hook in Claude settings, test no-change, failing, repaired, retry-limit, and success paths, and keep the full CI suite as an independent gate.

Example prompt
{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"bun run claude-hooks/index.ts"}]}]}}

What good looks like

  • The hook runs only when relevant files changed.
  • Failure output reaches the agent as one valid structured response.
  • Retries stop after a defined limit and surface unresolved errors.
  • Any commit contains only files changed for the current task.

Build your next product with ChatPRD

Turn an idea into a PRD, user stories, and a plan.

Try ChatPRD free

Runbook notes

How to recover when the loop fails and where human judgment helps.

If it goes sideways

The same failure causes an endless repair cycle
Track attempts by session, cap retries, and return the final diagnostics to the user when the cap is reached.
Command output corrupts the JSON sent back to Claude
Keep standard output reserved for the hook response and send debug or command logs to standard error.
The stop hook makes every task wait on the full suite
Map changed files to focused checks and reserve expensive suites for CI or explicit requests.
The success path commits unrelated user changes or secrets
Build an explicit allowlist from the task diff, scan it, and skip automatic commit when ownership or sensitivity is unclear.

Related workflows

Illustrated workflow: draft a sales deck with Claude Duet, review the content, and refine the design.
intermediateSalesClaudeGoogle Docs

How to Draft a Sales Deck on Your Phone Using Claude Duet

Generate a draft sales presentation in Google Docs directly from your phone using Claude Duet. This workflow is ideal for business users who need to create serviceable first drafts on the go without being at a computer.

Open
Illustrated example: connect sales apps, request a pipeline summary, and validate its findings.
beginnerSalesClaude

Analyze Your Sales Pipeline Using Claude Duet's Connected Apps

Use Claude Duet on your phone to quickly synthesize your sales pipeline by leveraging its connections to your existing business apps like your CRM, email, and Slack, saving you from manual data assembly.

Open
Illustrated workflow for building and testing a Reddit Proto prototype with signed-in data.
intermediateProductReddit ProtoCursor

Create a Realistic Prototype with Live Data in Reddit Proto

Use Reddit's internal prototyping tool, Reddit Proto, to build a working prototype of a new feature, like search, and test it with your own signed-in Reddit data for more realistic feedback.

Open

Start shipping better products.

Join 250,000+ product managers who use ChatPRD to write better docs, align teams faster, and build products users love.

Start building freeRequest a demo
Free to start · 14-day Pro trial · SOC 2 Type II