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 main   # show the prompt-mode input, run nothing

Fleet sync

scripts/sync-commands.sh pushes selected commands, skills, scripts and output styles to a list
of servers over SSH/rsync and can activate an output style remotely. Hosts and file lists live in
sync-commands.conf (gitignored — copy sync-commands.conf.example). --check compares every
configured file against each server (POSIX cksum) and reports MISSING / DRIFT / unmanaged files,
exit 2 on findings; --dry-run shows what would transfer.

Tests

bats tests/        # 57 tests: guard patterns, SQL guard, formatter, session marker, handoff, reviewer backend, wiring

CI runs the same suite on ubuntu; macOS bash 3.2 is the primary target. The backend tests run
against fake codex/claude executables that record their arguments — no model is ever called.

Background

The git guard exists because a chained git add -A && … && git commit once swept a parallel
session's work into a commit. The incident, the approaches that were tried and rejected, and the
measured hook costs are in docs/git-staging-safety.md. Why the
reviewer never sees the brief, why --restricted and not --bare, measured review times, and what
the reviewers found in this port are in docs/review-backend.md.

Not included

• My commit/push command (couples to private tooling; the staging discipline it implements is in
  the doc above).
• 20 SEO skills and 12 agents that sit next to these files in my config — they are
  AgriciDaniel's claude-seo (MIT), not mine.
• Anything client-specific. Scrubbed by grep before every commit.

Differences from my private copy

• Absolute paths → ${CLAUDE_PLUGIN_ROOT} / $HOME.
• git-staging-guard.sh judges git commit flags per token, so --all and -a --amend are
  caught too (the private copy missed both).
• sql-guard.sh was a jq | read one-liner in settings.json that only saw the first line of a
  command; it now checks every line and has the same prefilter as the git guard.
• session-start.sh keys the marker file by session id (${CLAUDE_SESSION_ID}) instead of an
  undocumented env-file export, and adds the dirty-file / blob snapshot.
• critical-review.md calls scripts/review-backend.sh instead of the Codex plugin's companion
  script (my copy is pinned to Codex), logs with python3 instead of node, and stops instead of
  reviewing its own diff when no reviewer is available.
• format-file.sh reads the file path from the hook JSON itself, no jq wrapper needed.
• sync-commands.sh config moved to sync-commands.conf; --help works without one; empty
  SERVERS is an error, not a silent no-op.

License

MIT — see LICENSE.