Stop your AI coding agent from saying "Done" until your code actually typechecks and lints.
Mechanical verification hooks for Claude Code and Codex — zero dependencies, auto-detects your stack, cross-platform.
Prompts are requests. Hooks are guarantees.
Your agent finishes a task. Before it's allowed to stop, the Stop gate runs:
Claude: "Done! I've implemented the feature."
└→ stop-verify fires
├→ tsc --noEmit (60s timeout)
├→ eslint (15s timeout)
├→ errors scoped to the files YOU changed (not pre-existing debt)
└→ errors found? → BLOCKED. "Fix these first."
└→ 3 consecutive blocks? → circuit breaker allows stop + final warning
Before Clawback: the agent says "Done!", you discover the type error. With Clawback: "Done!" → blocked → fixed → actually done.
No more "the code compiles in my imagination."
npx @lzong.tw/clawbackThat's it. Open Claude Code and type /hooks to verify. Add --with-codex to install the same guardrails into Codex.
# keep it around as a global binary instead
npm install -g @lzong.tw/clawback && clawback# or from source
git clone https://github.com/LZong-tw/clawback.git && cd clawback && node install.cjsOne install wires up hooks that fire automatically — whether the agent wants them to or not.
| Hook | Event | What it does |
|---|---|---|
| protect-files | PreToolUse | Blocks edits to .env, lockfiles, .git/ — before the agent touches them |
| post-edit | PostToolUse | Formats your code, then lints it (report-only) — after every edit |
| stop-verify | Stop | Runs full typecheck + lint — the agent can't say "Done!" until it passes |
| post-compact | SessionStart | Re-injects git state + gotchas.md on every session start, including after compaction (Codex: PostCompact) |
| notification | Notification | Desktop notification when the agent needs your attention |
Plus a behavioral CLAUDE.md that handles what hooks can't: phased execution, anti-sprawl limits, mistake logging.
Optional extras at install time: --with-read-guard blocks reads of common credential directories, --strict-infra also blocks edits under .husky/ and .github/workflows/, and --with-ui-guard adds TSX-specific UI anti-pattern warnings after edits.
Clawback auto-detects your project. You don't configure anything.
| Detected via | Typecheck | Lint | Format |
|---|---|---|---|
tsconfig.json |
tsc --noEmit |
eslint |
prettier |
go.mod |
go build |
go vet |
gofmt |
Cargo.toml |
cargo check |
cargo clippy |
cargo fmt |
pyproject.toml |
mypy / pyright |
ruff / flake8 |
ruff / black |
composer.json |
phpstan |
pint / php-cs-fixer |
pint |
No config file found? Hooks silently no-op. No errors, no noise.
Monorepo? Walk-up detection finds the nearest config from the edited file's directory. Different sub-projects use different tools automatically.
Your stack not listed? Extend it without forking.
┌─────────────────────────────────────────────────────┐
│ CLAUDE.md (behavioral guidance) │
│ "Don't touch >5 files per response" │
│ "Re-read files after 10+ messages" │
│ "Log mistakes to gotchas.md" │
│ → Claude follows these. Usually. Hopefully. │
├─────────────────────────────────────────────────────┤
│ Hooks (mechanical enforcement) │
│ protect-files → BLOCKED. Period. │
│ stop-verify → tsc fails? Can't stop. Period. │
│ post-edit → Formatted. Linted. Every time. │
│ → These fire whether Claude wants them to or not. │
└─────────────────────────────────────────────────────┘
The prompt layer asks. The hook layer enforces. Clawback is mostly the second one.
We document what doesn't work instead of hiding it.
- Bash bypass:
echo secret > .envvia Bash bypasses protect-files. Use Claude Code's built-in permission deny rules for shell safety. - Strict infra is opt-in:
.husky/and.github/workflows/are only blocked with--strict-infra(orCLAWBACK_STRICT_INFRA_PROTECTION=1). - UI guard is heuristic:
--with-ui-guardemits context for common TSX layout/input mistakes, not a formal compiler check. - Windows notifications: Console bell only. No desktop toast. (PRs welcome.)
- Anti-sprawl: "Max 5 files per response" is CLAUDE.md guidance, not a hook. The hooks API has no concept of response boundaries.
- Large TypeScript:
tsctimeout is 60s. Projects over 100k LOC may need incremental builds. - TS 5.0–5.1 monorepos:
tsc --build --noEmitis unsupported in those versions. Upgrade to 5.2+.
On March 31, 2026, Claude Code's source map leaked via npm. Inside, the community found employee-only verification loops gated behind USER_TYPE === 'ant' — Anthropic engineers got a Claude that checks whether generated code actually compiles before claiming it's done; everyone else got "Done!" and hope.
That leak was the prompt, not the point. The point is that every coding agent should refuse to call a task finished until the machine has verified it. Clawback implements that guarantee through Claude Code's and Codex's public hooks API — no flags, no auth bypass, no patched binary.
Hooks are 100% stack-agnostic. Every hook delegates to detect-stack.cjs — the single file that knows about languages. Adding Java support means editing one file, not five.
Zero external dependencies. Node.js built-ins only. No node_modules, no supply chain risk, no version conflicts.
Cross-platform. Windows (Git Bash / MINGW64), macOS, Linux. Path handling via path.join(), subprocess safety via platform-aware exec.cjs.
Shell-safe hook commands. Installed commands use node "absolute/path" rather than POSIX env-prefixes or single-quoted Windows paths, so the same command shape works in cmd.exe, PowerShell, and POSIX shells.
Idempotent. Run the installer ten times. You get one set of hooks, not ten duplicates.
Safe to remove. Uninstall reverses everything; your settings go back to how they were.
npx @lzong.tw/clawback --with-read-guard # also block reading ~/.ssh, ~/.aws, ~/.gnupg
npx @lzong.tw/clawback --strict-infra # also block edits to .husky/ and .github/workflows/
npx @lzong.tw/clawback --with-ui-guard # also warn on common TSX UI anti-patterns
npx @lzong.tw/clawback --with-codex # also install ~/.codex/hooks.json + ~/.codex/hooks/What it installs: hook scripts + lib modules to ~/.claude/hooks/, merges hook config into ~/.claude/settings.json (preserving your existing hooks), and appends behavioral guidance to ~/.claude/CLAUDE.md (preserving your existing rules). With --with-codex, it copies the same hooks to ~/.codex/hooks/, merges ~/.codex/hooks.json, and installs verify-global-hooks.cjs to regression-test cmd.exe / PowerShell / POSIX command quoting and the reinject hook's output. On Claude Code the reinject hook runs on SessionStart; on Codex it runs on PostCompact.
npx -p @lzong.tw/clawback clawback-uninstall # if you installed via npx
clawback-uninstall # if you installed globally
node uninstall.cjs # if you installed from sourceAny of these restores your original settings cleanly.
Create ~/.clawback/detect-stack.local.js:
module.exports = function(startDir, projectRoot) {
const fs = require('fs');
const path = require('path');
if (fs.existsSync(path.join(projectRoot, 'build.gradle'))) {
return {
typecheck: { cmd: 'javac', args: ['-d', '/tmp/clawback/classes'] },
lint: { cmd: 'checkstyle', args: ['-c', '/google_checks.xml'] },
lintFile: { cmd: 'checkstyle', args: ['-c', '/google_checks.xml'] },
sourceExtensions: ['.java', '.kt'],
lockfiles: ['gradle.lockfile'],
};
}
return null;
};Your local overrides take priority over built-in detection.
~/.claude/hooks/
├── lib/
│ ├── detect-stack.cjs ← sole language-aware module
│ └── exec.cjs ← cross-platform safe subprocess
├── protect-files.cjs ← PreToolUse (Edit|Write)
├── post-edit.cjs ← PostToolUse (Edit|Write)
├── stop-verify.cjs ← Stop (circuit breaker)
├── post-compact-reinject.cjs ← SessionStart (Claude) / PostCompact (Codex)
├── notification.cjs ← Notification
├── guard-read.cjs ← optional PreToolUse (Read)
├── ui-antipattern-check.mjs ← optional PostToolUse (Edit|Write)
└── clawback-manifest.json ← tracks what was installed
npm test # 59 tests, zero dependenciesFor Codex installs, the generated global hook file can also be checked directly:
node ~/.codex/hooks/verify-global-hooks.cjsThis project went through 9 rounds of adversarial design review before a single line of code was written, then 4 more rounds of code-level attack on the implementation plan. Every finding was fixed. The final review returned: "No further issues."
Full design spec | Implementation plan
- production-verify — Production verification framework (smoke tests + architecture proofs)
- Claude Code Hooks Guide — Official hooks documentation
PRs welcome. The architecture is designed for contribution:
- New language support? Edit
lib/detect-stack.cjsonly. No hook changes needed. - New hook? Add to
hooks/, register ininstall.cjs. Existing hooks untouched. - Bug fix? 59 tests protect you from regressions.
LZong — DevOps engineer. Building tools that make AI coding actually reliable.
MIT