Clawback

Give Claude Code the verification loops Anthropic reserves for their own engineers.

The Story

On March 31, 2026, Claude Code's source map leaked via npm. Inside 512,000 lines of code, the community discovered something interesting: employee-only verification loops gated behind USER_TYPE === 'ant'.

Anthropic engineers get a Claude that checks whether generated code actually compiles before claiming it's done. The rest of us get a Claude that says "Done!" and hopes for the best.

Clawback takes those patterns back. Not by hacking flags or bypassing auth -- but by implementing the same behavioral guarantees through Claude Code's public hooks API.

"Prompts are requests, hooks are guarantees."

What It Does

One node install.cjs and your Claude Code gets 5 hooks that fire automatically. Add --with-codex and the same guardrails are installed into Codex global hooks with shell-safe command quoting:

| Hook | Event | What It Does | |------|-------|--------------| | protect-files | PreToolUse | Blocks edits to .env, lockfiles, .git/ -- before Claude touches them | | post-edit | PostToolUse | Formats your code, then lints it (report-only) -- after every edit | | stop-verify | Stop | Runs full typecheck + lint -- Claude can't say "Done!" until it passes | | post-compact | PostCompact | Re-injects git state + gotchas.md after context compaction | | notification | Notification | Desktop notification when Claude needs your attention |

Plus a behavioral CLAUDE.md that handles what hooks can't: phased execution, anti-sprawl limits, mistake logging.

Optional extras can be enabled at install time: read-guard blocks reads of common credential directories, strict-infra also blocks edits under .husky/ and .github/workflows/, and ui-guard adds TSX-specific UI anti-pattern warnings after edits.

The Stop Gate

This is the core feature. When Claude tries to complete a task:

Claude: "Done! I've implemented the feature."
  └→ stop-verify fires
       ├→ tsc --noEmit (60s timeout)
       ├→ eslint (15s timeout)
       ├→ errors scoped to files YOU changed (not pre-existing debt)
       └→ errors found? → BLOCKED. "Fix these first."
           └→ 3 consecutive blocks? → circuit breaker allows stop + final warning

No more "the code compiles in my imagination."

Zero Config, Any Stack

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.

Install

Via npm (recommended)

npx @lzong.tw/clawback

That's it. Open Claude Code, type /hooks to verify.

If you prefer to keep it around as a global binary:

npm install -g @lzong.tw/clawback
clawback

From source

git clone https://github.com/LZong-tw/clawback.git
cd clawback
node install.cjs

Options

Install-time flags work the same regardless of how you invoke Clawback:

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 after edits
npx @lzong.tw/clawback --with-codex         # also install ~/.codex/hooks.json + ~/.codex/hooks/
# or
node install.cjs --with-read-guard
node install.cjs --strict-infra
node install.cjs --with-ui-guard
node install.cjs --with-codex

What it installs

• 5 hook scripts + 2 lib modules to ~/.claude/hooks/
• Optional extra hooks when requested with --with-* flags
• Merges hook config into ~/.claude/settings.json (preserves your existing hooks)
• Appends behavioral guidance to ~/.claude/CLAUDE.md (preserves your existing rules)
• With --with-codex, copies the same hooks to ~/.codex/hooks/, merges ~/.codex/hooks.json, and installs verify-global-hooks.cjs to regression-test Windows cmd.exe, PowerShell, POSIX-shell-safe command quoting, and Codex-compatible PostCompact JSON output.

Uninstall

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 source

Any of these restores your original settings cleanly.

Design Principles

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-in modules 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 hook commands use node "absolute/path" instead of POSIX env-prefixes or single-quoted Windows paths, so the same generated command shape works in cmd.exe, PowerShell, and POSIX shells.

Idempotent. Run node install.cjs ten times. You get one set of hooks, not ten duplicates.

Safe to remove. node uninstall.cjs reverses everything. Your settings go back to how they were.

Adding Custom Stacks

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.

Architecture

~/.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   ← PostCompact
├── notification.cjs            ← Notification
├── guard-read.cjs              ← optional PreToolUse (Read)
├── ui-antipattern-check.mjs    ← optional PostToolUse (Edit|Write)
└── clawback-manifest.json      ← tracks what was installed

How the Two Layers Work

┌─────────────────────────────────────────────────────┐
│  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.  │
└─────────────────────────────────────────────────────┘

Known Limitations

We believe in documenting what doesn't work, not hiding it.

• Bash bypass: echo secret > .env via 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 when installed with --strict-infra or when CLAWBACK_STRICT_INFRA_PROTECTION=1 is set for the hook.
• UI guard is heuristic: --with-ui-guard emits additional 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: tsc timeout is 60s. Projects over 100k LOC may need incremental builds.
• TS 5.0-5.1 monorepos: tsc --build --noEmit not supported in these versions. Upgrade to 5.2+.

Testing

npm test    # 52 tests, zero dependencies

For Codex installs, the generated global hook file can also be checked directly:

node ~/.codex/hooks/verify-global-hooks.cjs

Reviewed to Death

This project went through 9 rounds of adversarial design review before a single line of code was written. The implementation plan was then reviewed through 4 more rounds of code-level attack. Every finding was fixed. The final review returned: "No further issues."

Full design spec | Implementation plan

Related

• production-verify -- Production verification framework (smoke tests + architecture proofs)
• Claude Code Hooks Guide -- Official hooks documentation

Contributing

PRs welcome. The architecture is designed for contribution:

• New language support? Edit lib/detect-stack.cjs only. No hook changes needed.
• New hook? Add to hooks/, register in install.cjs. Existing hooks untouched.
• Bug fix? 51 tests protect you from regressions.

Author

LZong -- DevOps engineer. Building tools that make AI coding actually reliable.

License

MIT