claude-code-guardrails

Hooks, commands and an output style I use with Claude Code, extracted from my private config.

• Hooks — run outside the model's judgment: block bulk git add / git commit -a and WHERE-less SQL before the Bash call executes, record the session-start commit, snapshot work state before context compaction, run the project's own formatter after edits.
• Commands — a delivery loop (/plan → /implement → /verify → /critical-review → /crosscheck) and doc-maintenance commands (/save-learnings-to-docs, /cleanup-docs, /refactor-claude-md, /init-local-md).
• Reviewer backend — /critical-review runs an independent, read-only reviewer on the diff (Codex CLI, Claude Code CLI, or your own command) through one adapter script, and never shows it the task brief.
• Output style — terse.md: result first, no padding.
• Fleet sync — push commands/skills/styles to your servers over SSH, audit drift with --check.

Install

As a plugin (Claude Code ≥ 2.1):

/plugin marketplace add tillmeier/claude-code-guardrails
/plugin install guardrails@tillmeier

Restart Claude Code. Hooks are active immediately; commands are namespaced (/guardrails:plan, /guardrails:verify, /guardrails:critical-review, …); the output style is selectable with /output-style Terse.

By hand (bare /plan, /verify, … and control over which hooks run):

git clone https://github.com/tillmeier/claude-code-guardrails ~/claude-code-guardrails
cp ~/claude-code-guardrails/commands/*.md      ~/.claude/commands/
cp ~/claude-code-guardrails/output-styles/*.md ~/.claude/output-styles/

then wire the hooks you want into ~/.claude/settings.json. /critical-review looks for its backend script at ~/claude-code-guardrails/scripts/review-backend.sh; for a checkout elsewhere, export REVIEW_BACKEND=<checkout>/scripts/review-backend.sh. Wire the hooks:

"hooks": {
  "SessionStart": [{"hooks": [{"type": "command", "command": "bash \"$HOME/claude-code-guardrails/hooks/session-start.sh\""}]}],
  "PreToolUse": [{"matcher": "Bash", "hooks": [
    {"type": "command", "command": "bash \"$HOME/claude-code-guardrails/hooks/sql-guard.sh\"", "timeout": 10},
    {"type": "command", "command": "bash \"$HOME/claude-code-guardrails/hooks/git-staging-guard.sh\"", "timeout": 10}
  ]}],
  "PostToolUse": [{"matcher": "Edit|Write|MultiEdit", "hooks": [{"type": "command", "command": "bash \"$HOME/claude-code-guardrails/hooks/format-file.sh\""}]}],
  "PreCompact": [{"hooks": [{"type": "command", "command": "bash \"$HOME/claude-code-guardrails/hooks/precompact-handoff.sh\""}]}]
}

Requirements: bash ≥ 3.2, git, python3. /critical-review needs one reviewer: the Codex CLI (logged in), the Claude Code CLI, or a command of your own (see Reviewer backend). Tests need bats-core; the fleet sync needs ssh + rsync.

Hooks

A blocked call exits 2; the tool call never runs and the model gets the stderr as the reason:

$ git add -A && git commit -F -
BLOCKED by git-staging-guard: bare `git add` sweep (-A / --all / . / :/) with no explicit `--` pathspec

  offending segment: git add -A

Stage explicitly instead — name the files:
  git add <path> [<path>...]
  git diff --cached --name-only     # then read the index back before committing
[...]

$ git add hooks/git-staging-guard.sh tests/guard.bats
$ git commit -m "guard: judge commit flags per token"

Notes:

• Only exit 2 blocks a tool call; exit 1 is a non-blocking notice and the call proceeds. The tests assert exit codes, not just messages.
• The two Bash guards gate on a pure-bash prefilter and only parse JSON when the payload could match, so they cost ~milliseconds on unrelated calls. Numbers in docs/git-staging-safety.md.
• They are habit guards, not sandboxes: they inspect text, and an unusual spelling can evade them. A payload that merely mentions a guarded command (docs, commit messages) passes — and if it trips the guard anyway, write it with Edit/Write instead of Bash.

Commands

The loop in practice: docs/workflow-recipes.md. Plan files land in .claude/plans/, gitignore them if you don't want them tracked.

Reviewer backend

scripts/review-backend.sh is the only vendor-specific piece behind /critical-review. It picks a reviewer, assembles the review input from git (the diff; for the working tree also untracked file bodies), runs the reviewer read-only and prints the review — plus one stderr line saying which backend, model and mode actually ran.

Untracked symlinks are listed but never followed, so a link to a file outside the repository cannot ship that file to the reviewer. Unset, it auto-detects in that order (custom command configured → codex logged in → claude) and refuses with exit 3 and the list of what it checked when nothing is usable. A backend you name explicitly but that is unavailable is also exit 3 — never a silent substitute. Models are pinned in review-backend.conf (copy scripts/review-backend.conf.example to ~/.claude/review-backend.conf; the real file is gitignored): a vendor default can be deprecated or unavailable on your account without warning. Prompt-mode output follows scripts/review-findings.schema.json.

The reviewer is deliberately given no way to receive the task brief: framing a change as intended or bug-free collapses a reviewer's true-positive rate (arXiv 2603.18740). /critical-review writes the brief for itself and applies it only after the review, behind a mandatory re-read of the source.

One honest caveat: a Claude reviewer of Claude-written code is a fresh context, not an independent model. It catches what the author-context missed, but shares the model's blind spots. Codex or another vendor is the real second opinion; claude is the fallback when that is not installed.

bash scripts/review-backend.sh --detect                     # which reviewer would run
bash scripts/review-backend.sh --base HEAD~3                # review the last three commits
bash scripts/review-backend.sh --scope working-tree --focus "error handling in the retry path"
bash scripts/review-backend.sh --print-prompt --base ma