Claude Code tsc hook: does type-checking on edit help?

Does a hook that runs tsc after every edit make Claude Code leave fewer TypeScript errors behind? I measured it in 300 claude -p runs on a 53-file strict TypeScript project. On single refactors it made no difference: Haiku 5.5 and Sonnet 5.5 left type errors in 1 of 240 runs, and that one run had no hook. On a bigger request with no shell access it made all the difference: Sonnet edited only the core files and left 148 errors in 9 of 9 runs without a blocking hook, and 0 errors in 6 of 6 runs with one. And the common way to write the hook, exit 1 on failure, does nothing at all: Claude never sees the errors.

This is a post in the Claude Code series, where I test the tool this site runs on with scripted runs. Earlier ones measured deny rules on a .env file and .claudeignore on a lockfile, the other settings people add to keep an agent in line.

How I tested it

The test project is a small order system: types, an in-memory store, pricing, reports, a CLI, plus notification channels, regional tax tables, carriers, admin views, batch jobs and test-data builders. I wrote the 13 core files by hand and generated the other 40 from six templates (bench/gen_fixture.py), so that a change to a core type has to reach many files that use it in different ways: destructuring, Record<OrderStatus, ...> tables, exhaustive switch statements with assertNever, an injected store, object literals. TypeScript 7.0.2 with strict and noUncheckedIndexedAccess, 1,054 lines.

Six tasks, each one prompt a developer might type. Here is how far each change ripples if you only edit the core type (bench/ripple.sh):

Task	Prompt (shortened)	tsc errors after the core change alone
refunded	Add a refunded status: closed, reachable from paid or shipped, zero revenue	18 in 16 files
cents	Replace unitPrice with integer unitPriceCents, keep printing dollars	24 in 21 files
find-undefined	findOrder returns undefined instead of throwing, CLI prints a friendly message	77 in 17 files
async-store	Make every OrderStore method async	94 in 17 files
currency	Add a required currency field and print its symbol	7 in 5 files
name-split	Replace Customer.name with firstName and lastName	25 in 24 files

Five conditions:

• none: just the prompt.
• claude-md: a CLAUDE.md that says “After any change to TypeScript files, run npx tsc --noEmit and fix every error before you say you are done.”
• post-exit1: a PostToolUse hook on Edit|Write|MultiEdit that runs tsc --noEmit and exits 1 on errors.
• post-exit2: the same hook, exiting 2.
• stop-exit2: the same check as a Stop hook, so it runs when Claude tries to finish.

Each condition ran with Bash allowed (a list of commands: npx, npm, node, tsc, grep, sed and a few more) and with no shell, only the file tools, which is what a plain claude -p without Bash permissions gets. Two models, two repetitions: 240 runs. After each run the grader counted tsc errors in a fresh check and ran hidden acceptance tests for the task (node --test, never copied into the work folder), compiled even if tsc failed, so a run could be type-clean and wrong or the other way round.

Claude Code was 2.1.319. Every run had no MCP servers, no auto-memory and --setting-sources project.

Does a tsc hook reduce TypeScript errors in Claude Code?

Not on these refactors. Every one of the 240 runs passed its hidden tests, and 239 ended with zero type errors:

Runs with tsc errors left (of 12)	none	claude-md	post-exit1	post-exit2	stop-exit2
Haiku, Bash allowed	0	0	0	0	0
Haiku, no shell	0	0	0	0	0
Sonnet, Bash allowed	0	0	0	0	0
Sonnet, no shell	1 (28 errors)	0	0	0	0

The one miss was the currency task: Sonnet changed formatMoney to take a currency, updated the core files, and never opened the admin views, which still called it with one argument.

With Bash allowed, both models checked their own work without being asked: the median run tried tsc 4.5 to 8.5 times. Without a shell they read and searched the files and got it right anyway. A hook had nothing to catch.

When does the hook matter?

When the request is big enough that the model stops early. I put all six changes into one numbered prompt and ran it three times per condition and model, without a shell.

All six changes at once, no shell	none	claude-md	post-exit1	post-exit2	stop-exit2
Sonnet: tsc errors left per run	148, 148, 148	148, 148, 148	148, 148, 148	0, 0, 0	0, 0, 0
Sonnet: median time	46 s	43 s	49 s	172 s	163 s
Sonnet: mean cost per run	USD 0.17	USD 0.16	USD 0.17	USD 1.04	USD 0.63
Haiku: tsc errors left per run	0, 0, 0	0, 148, 0	0, 0, 8	0, 0, 0	0, 0, 0
Haiku: median time	237 s	208 s	261 s	252 s	240 s

Sonnet did the same thing in all nine runs without a blocking hook: it made 11 to 14 edits to the core files, wrote a tidy summary of all six changes and stopped. The 148 errors it left were spread over all 40 generated modules, which it never opened. The CLAUDE.md instruction did not help either: with no shell Sonnet could not run tsc, and it said so in all three summaries (“I made all six changes, but I couldn’t run npx tsc --noEmit”), but it stopped anyway. With the Stop hook, the first attempt to finish got this back, every time:

Stop hook feedback:
["$CLAUDE_PROJECT_DIR"/.claude/hooks/tsc-check.sh stop 2]: TypeScript check failed (148 errors). Fix them before continuing:
src/admin/customerOrders.ts(14,45): error TS2339: Property 'customerId' does not exist on type 'Promise<Order | undefined>'.
...

Sonnet went back to work and the second Stop check passed: 58 to 83 edits in total, against 11 to 14 without the hook. It hit the same 148 errors at the same point in all three runs, so the hook did not change how Sonnet worked, only when it was allowed to stop.

Haiku was slower and more thorough: it ended clean in 7 of 9 runs without a blocking hook. Its two misses were a run that stopped at 37 turns (148 errors) and a run with the silent exit 1 hook that ended with 8 syntax errors (Type expected) in the admin views.

With Bash allowed, the same combo prompt ended clean in 29 of 30 runs. Both models ran tsc themselves, 7 to 29 times per run, and fixed what it reported. The miss was a Sonnet run with the exit 1 hook that rewrote the generated files with perl through Bash (which an Edit|Write matcher does not see), imported two helpers it never added, and ended with 66 errors. So the hook is mostly insurance for the runs where Claude cannot or does not check.

Why does an exit 1 hook do nothing?

Because Claude Code treats exit 1 as a broken hook, not as a failed check. The hooks reference says it directly: “Exit code 1 without valid JSON output is a non-blocking error … even though 1 is the conventional Unix failure code. If your hook is meant to enforce a policy, use exit 2.” For PostToolUse, exit 2 “shows stderr to Claude; the tool already ran”.

The transcripts show it. In the 240 single-task runs, the exit 1 hook produced reports that Claude Code stored as hook_non_blocking_error with nothing sent to the model; the exit 2 hook’s reports were stored as hook_blocking_error and rendered into the conversation as a system reminder after the edit:

Hook	Reports with tsc errors (240 runs)	Stored as	Shown to Claude
PostToolUse, exit 1	1,078	hook_non_blocking_error	0
PostToolUse, exit 2	985	hook_blocking_error	985

A script that ends with tsc --noEmit || exit 1 will look like it works when you test it in a terminal. So will one that lets tsc’s own exit status through, and that one has a trap: on this project TypeScript 5.9.3 exits 2 on type errors and TypeScript 7.0.2 exits 1. The same hook goes silent after the upgrade.

None of this shows up in --output-format stream-json: across 240 streams there was no hook event at all, only init, thinking_tokens, permission_denied and task events, which is open as claude-code#94275. I counted hook output from the session transcript (~/.claude/projects/<folder>/<session-id>.jsonl, found with --session-id) and from the hook’s own log.

PostToolUse or Stop hook?

Stop, from these numbers. The PostToolUse hook ran after every .ts edit, and a multi-file refactor stays broken until its last edit, so 94% of its reports (2,063 of 2,196) said there were errors. The models worked through them, but they cost tokens:

Mean cost per run, single tasks	none	post-exit2	stop-exit2
Sonnet, Bash allowed	USD 0.184	USD 0.234	USD 0.177
Sonnet, no shell	USD 0.178	USD 0.293	USD 0.179
Haiku, Bash allowed	USD 0.030	USD 0.024	USD 0.019
Haiku, no shell	USD 0.015	USD 0.022	USD 0.015

On the combo task the PostToolUse hook cost Sonnet USD 1.04 per run against USD 0.63 for the Stop hook, for the same result. The Stop hook ran once when the code was already clean and twice when it was not. Costs are what Claude Code reports at API prices; these runs used a subscription.

Two things to know about Stop hooks from the docs: Claude Code stops honoring a Stop hook after it has blocked eight times in a row without a tool call in between (CLAUDE_CODE_STOP_HOOK_BLOCK_CAP raises that), and the input has stop_hook_active so a hook can tell it already blocked once. Neither came up here: the most any run needed was one block.

What does the hook cost in time?

Less than you might think with TypeScript 7. On an idle machine, tsc --noEmit on this project took a median 0.18 s with TypeScript 7.0.2 and 1.29 s with 5.9.3 (20 runs each), and the whole hook, including the node call that reads the input JSON, about 0.22 s. In the benchmark, with five runs in parallel, a hook call took a median 0.48 s, so the PostToolUse hook spent 5 to 12 s per task in tsc.

Measured per task, the median with the exit 2 PostToolUse hook was 6 to 16 s longer than with no hook (Sonnet with Bash: 39 s against 51 s), and with the Stop hook between 2 s shorter and 10 s longer. On the combo task without a shell, the hooks made Sonnet take 163 to 172 s instead of 46 s, because it did the work it had skipped. With a large project and TypeScript 5, a PostToolUse hook pays the full check after every edit; that is where the Stop version saves the most.

The hook script

#!/usr/bin/env bash
# Usage: tsc-check.sh <post|stop> <exit code on type errors>
event="$1"; fail_code="${2:-2}"
input="$(cat)"
if [ "$event" = post ]; then
  file="$(printf '%s' "$input" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const j=JSON.parse(s);console.log((j.tool_input&&j.tool_input.file_path)||"")})')"
  case "$file" in *.ts) ;; *) exit 0 ;; esac
fi
cd "$CLAUDE_PROJECT_DIR" || exit 0
out="$(./node_modules/.bin/tsc --noEmit --pretty false 2>&1)"; status=$?
if [ $status -ne 0 ]; then
  { echo "TypeScript check failed ($(printf '%s\n' "$out" | grep -c 'error TS') errors). Fix them before continuing:"
    printf '%s\n' "$out" | head -30; } >&2
  exit "$fail_code"
fi
exit 0

And in .claude/settings.json, the Stop version:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tsc-check.sh stop 2", "timeout": 60 }] }
    ]
  }
}

The full script in the repo also writes a log line per run when HOOK_LOG is set; that is how I counted the runs.

What broke, and what I did not measure

• My user CLAUDE.md leaked into the first runs. With the work folders under my home folder, claude -p --setting-sources project still loaded ~/.claude/CLAUDE.md, and one Haiku run spent turns looking for a memory tool that file mentions. In /tmp it did not load. All 300 runs here ran under /tmp.
• A copied node_modules broke tsc. My first harness copied the fixture with symlinks resolved, so node_modules/.bin/tsc became a file whose relative import pointed nowhere. The hook failed on every edit with “0 errors”. Haiku noticed, ran the compiler by its real path, finished the task and explained the broken shim in its summary. Worth knowing: a hook that fails for its own reasons looks to Claude like a failing check.
• The first fixture was too easy. With 13 files, Haiku with no shell and no hook left 0 errors on all six tasks, so I added the generated modules. That is a choice that favors the hook; a real codebase is less repetitive, which can make call sites both harder and easier to find.
• Bash was a list, not a free shell. 595 commands were denied in the Bash-allowed runs (cd ... &&, sed -i, pipes into tsc); the models retried in another form. With full Bash they might check even more.
• Small samples. Two repetitions per cell on the single tasks and three on the combo. The combo results were the same in every repetition for Sonnet, which is why I trust that one.
• Not tested: Opus, interactive sessions, ESLint or tests in the hook, asyncRewake hooks, a PreToolUse check, and projects where tsc takes more than a second.

In total: 300 runs, Claude Code 2.1.319, USD 45.97 at API prices as Claude Code reports it (USD 26.05 for the single tasks, 19.92 for the combo), on a subscription, run on a laptop with a 4-thread CPU and 19 GB of RAM.

Should you add a tsc hook to Claude Code?

• Yes, as a Stop hook that exits 2. It costs one tsc run when the work is already right, and it turned 148 errors into 0 when the model stopped early. It is the cheapest insurance in this test.
• Never exit 1. Claude does not see it. If your hook script lets tsc pick the exit code, whether Claude sees anything depends on your TypeScript version: 5.9.3 exited 2 here, 7.0.2 exits 1. Exit 2 explicitly.
• A PostToolUse hook works but is noisy on multi-file changes: nearly every report is an error the model already plans to fix, and on Sonnet it cost 27% to 64% more per task for no change in the result.
• A CLAUDE.md line is not the same thing. It asks the model to check; with no shell it could not, and on the combo task it changed nothing.
• If Claude has a shell, it mostly checks anyway. Haiku and Sonnet 5.5 ran tsc on their own in nearly every Bash-allowed run.

The fixture, the hook, the hidden tests, all 300 runs and the summary tables are in the project folder.