Claude Code Guardrails — Summary

Claude Code Guardrails is a bash-script bundle that installs three Claude Code hooks to prevent accidental code loss during AI-assisted development: a pre-write branch guard (PreToolUse), a post-write auto-commit snapshot (PostToolUse), and a session-end checkpoint squasher (Stop/PreCompact).

Problem it solves: Claude Code modifies files directly without warning when working on protected branches, can overwrite uncommitted manual changes, and produces messy git histories with hundreds of micro-checkpoint commits. The three hooks enforce branch safety, preserve intermediate states as git snapshots, and squash those snapshots into clean task commits at session end.

Distinctive trait: The four-hook configuration covers the full write lifecycle — PreToolUse blocks dangerous writes, PostToolUse captures each change as a snapshot commit, Stop squashes checkpoints into a task commit, and PreCompact squashes before context compaction. This is a complete git-safety harness delivered as a bash install script that intelligently merges with existing .claude/settings.json.

Target audience: Developers using Claude Code who have experienced "AI overwrote my uncommitted work" or "git history has 200 micro-commits from one coding session."

Production-readiness: Active but small project (54 stars, MIT, Shell, last commit September 2025). Bilingual documentation (English, Chinese, Japanese). Clean install script with backup/dedup/idempotent behavior.

Differs from seeds: Most similar to spec-kit's PostToolUse hooks (which auto-run tests) in using the hook lifecycle for automation, but Claude Code Guardrails exclusively targets git safety rather than quality gates. Unlike superpowers's using-git-worktrees skill (which isolates features), Guardrails operates in-place and focuses on protecting the working state via continuous snapshotting rather than isolation.

Claude Code Guardrails — Overview

Origin

Created by wangbooth. The README is trilingual (English, Chinese, Japanese), suggesting a Chinese-origin project with international audience in mind. GitHub: wangbooth/Claude-Code-Guardrails.

Philosophy

"Triple Security Mechanism: Pre-write Interception Alert + Precise Snapshot Commits + Smart Merge Archiving"

The framework addresses what the README calls "Dangerous Moments" in vibe coding:

• Direct modification on main branch
• Interrupted modifications (intermediate artifacts lost)
• Chaotic multiple modifications
• Accidentally deleted important files
• Manual changes overwritten by AI

Core Principles

1. Protected branch interception — Block writes to main branch, suggest creating feature branch
2. Uncommitted changes protection — Block when manual changes are uncommitted, force commit first
3. File-level precise snapshots — Each modification commits only changed files (not git add .)
4. Smart backup mechanism — Backup gitignore files to .claude/backups/ before modification
5. Safe history merging — Multiple checkpoints intelligently merged into clean task commits

Design Constraints

• Does not overwrite existing Claude Code Hooks — uses jq to intelligently merge .claude/settings.json
• Backup + deduplication + idempotent — safe to run multiple times
• Coexists with user hooks — does not affect existing hook configurations
• Project-level vs global installation — both supported

Claude Code Guardrails — Architecture

Distribution

• Type: bash-script-bundle + Claude Code settings injection
• License: MIT
• Language: Shell

Install Methods

# Project-level (recommended)
curl -fsSL https://raw.githubusercontent.com/wangbooth/claude-code-guardrails/main/install.sh | bash

# Global installation
curl -fsSL https://raw.githubusercontent.com/wangbooth/claude-code-guardrails/main/install.sh | bash -s -- --global

# From clone (local installation)
./install.sh --target /path/to/project

Required Runtime

• bash
• git (configured with user.name / user.email)
• jq (for JSON merging)
• Claude Code (hooks system)

Directory Structure

Claude-Code-Guardrails/
├── .claude/
│   ├── settings.json           # Hook definitions
│   └── hooks/
│       └── guardrails/
│           ├── guard-branch.sh      # PreToolUse: branch protection + uncommitted changes
│           ├── auto-commit.sh       # PostToolUse: file-level snapshot commit
│           └── squash-checkpoints.sh # Stop/PreCompact: squash into task commit
├── install.sh                  # Installer: merges settings.json, copies scripts
├── uninstall.sh                # Removes hooks + scripts
├── README.md                   # English
├── README_CN.md                # Chinese
└── README_JA.md                # Japanese

Hook Configuration (.claude/settings.json)

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Write|Edit|MultiEdit",
        "hooks": [{ "command": "...guard-branch.sh", "timeout": 10 }] }
    ],
    "PostToolUse": [
      { "matcher": "Write|Edit|MultiEdit",
        "hooks": [{ "command": "...auto-commit.sh", "timeout": 30 }] }
    ],
    "Stop": [
      { "hooks": [{ "command": "...squash-checkpoints.sh", "timeout": 30 }] }
    ],
    "PreCompact": [
      { "hooks": [{ "command": "...squash-checkpoints.sh compact", "timeout": 60 }] }
    ]
  }
}

Install Path Variants

• Project install: Scripts at $CLAUDE_PROJECT_DIR/.claude/hooks/guardrails/; settings in .claude/settings.json
• Global install: Scripts at ~/.claude/hooks/guardrails/; settings in ~/.claude/settings.json

Target AI Tools

Claude Code only (uses Claude Code's hook system exclusively).

Claude Code Guardrails — Components

Hooks (4 events → 3 scripts)

Scripts (3 bash scripts)

Install Scripts (2)

Backup Mechanism

Before modifying .gitignore or other tracked config files, auto-commit.sh backs up the original to .claude/backups/<filename>.bak.<timestamp>.

No Commands, Skills, MCP Servers

Pure hook automation. No slash commands, no skills, no MCP.

Claude Code Guardrails — Uniqueness

Differs from Seeds

Claude Code Guardrails is closest to spec-kit in using all four major hook events (PreToolUse, PostToolUse, Stop, PreCompact) for automation — but it automates git safety rather than quality checks. Unlike superpowers's using-git-worktrees skill (which isolates features in separate worktrees), Guardrails stays in-place and protects the current branch state through continuous snapshotting. Unlike claude-flow's worktree_per_feature: yes isolation, Guardrails does not create branches — it blocks writes to existing protected branches. The PreCompact hook (squash before compaction) is a capability no seed framework explicitly implements. The commits_automatically: yes behavior is shared with some seed frameworks but Guardrails does it with file-level precision (only changed files, not git add .) and includes a session-end squash that other frameworks lack.

Key Differentiators

1. Four-event complete lifecycle: The only framework in the corpus that hooks PreToolUse + PostToolUse + Stop + PreCompact for a complete write-lifecycle coverage.
2. File-level snapshots: Auto-commit only stages the files changed in the specific tool-use event, avoiding noise from git add ..
3. Session-end squash: Checkpoint commits created during the session are squashed into one clean task commit at Stop.
4. PreCompact squash: Squashes before context compaction — preventing history pollution at a boundary no other framework handles.
5. Intelligent settings merge: jq-based merge of existing settings.json — installs alongside other hooks without collision.

Positioning

Claude Code Guardrails occupies the "git safety automation" niche — protecting against the three most common vibe-coding git disasters: pushing to main, overwriting uncommitted work, and creating messy micro-commit histories. It does not improve code quality or enforce methodology — it only protects the state of the repository.

Observable Failure Modes

• Squash conflicts: If the session produced commits with diverging changes, git rebase interactive may conflict and block the squash.
• jq dependency: Missing jq blocks installation entirely (the script exits with a clear error, but it's a hard dependency).
• Squash identification: The squash script identifies checkpoints by commit message prefix "checkpoint:" — commits without this prefix (e.g., from other tools) may confuse the squash.
• Pre-commit hook interaction: If the repository has pre-commit hooks, the auto-commit after each write may be slow or fail.
• Global install context confusion: Global hooks apply to all Claude Code projects — blocking writes to main across all repos, even if some repos intentionally work on main.

Explicit Antipatterns

• Direct commits to main/master branch by the AI agent
• git add . instead of file-level staging (noise in commit history)
• Hundreds of micro-commits from a single session
• Losing intermediate work states when session is interrupted