Step01
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.
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.
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.
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
- Claude CodeVisitClaude Code
Claude for coding tasks
Step by step
The workflow
Follow the sequence once, then adapt the prompts, checks, and handoffs to your own setup.
5 steps
Step02
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.
Step03
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.
Step04
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.
Step05
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.
After the steps
Runbook notes
How to recover when the loop fails and where human judgment helps.
Recover
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.
Keep building
Related workflows
advancedEngineeringClaude
How to Implement AI Governance with Context-Aware Project Controls
Create context-aware guardrails for your enterprise AI agent using a 'Project' governance layer. As a project owner, define rules, scope tools, and require human-in-the-loop approval for sensitive actions, ensuring safe and effective AI use.
Open
intermediateOperationsKai (Stripe)
How to Turn a One-Off AI Chat Session into a Reusable Workflow for Your Team
Transform a successful AI chat session into a reusable skill that anyone in your company can use. Package prompts, tools, and code into a standardized workflow, making it easy to share and scale automation across your organization.
Open
beginnerDataKai (Stripe)
How to Create a Custom Data Dashboard On-the-Fly with a Natural Language AI Agent
Use a natural language AI agent to instantly generate and iterate on custom data dashboards. This workflow queries your company's data securely, allowing non-technical users to perform their own 'last mile' data analysis without filing tickets.
Open
Start shipping
better products.
Join 100,000+ product managers who use ChatPRD to write better docs, align teams faster, and build products users love.
Free to start
No credit card
SOC 2 certified
Enterprise ready