[DOCS] Hooks page would benefit from a concrete safety/recovery example

Resolved 💬 1 comment Opened Apr 20, 2026 by jinbowang1 Closed May 27, 2026

The Hooks docs explain how to wire up PreToolUse / PostToolUse / etc., but don't give a concrete example of the most valuable motivating use case: protecting the user from destructive Claude Code actions.

Today the examples lean toward observability / telemetry / bash validators. None show the "undo button" use case, which is what many users are looking for when they first find out hooks exist.

Suggested addition

A short example in the Hooks page (or an "Examples" subsection) showing:

  1. A PreToolUse hook that runs before Write, Edit, Bash that snapshots the project directory
  2. A companion CLI command to restore to the previous snapshot

One existing open-source implementation that does exactly this is cowback (npm: cowback). It uses native filesystem copy-on-write (clonefile() on macOS APFS, FICLONE on Linux BTRFS/XFS), so snapshots take a few ms and cost ~0 disk. cowback init claude writes the hook config. Not proposing it as the canonical example — just pointing out it exists and shows the shape a good example would take.

Why this matters

The rm -rf <computed-path> class of bug hits Claude Code users the same way it hits any shell-scripting developer. A visible "Hooks can give you undo, here's how" example would:

  • Surface a high-value pattern many users don't discover on their own
  • Give the docs a concrete "wow, hooks are powerful" moment
  • Reduce data-loss support requests

If there's interest

Happy to submit a PR against whatever repo holds the docs source once I know where. (The published site appears to be Mintlify-hosted and I couldn't locate the source in the public anthropics org — pointer appreciated.)

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗