cadence-guardrails
Safety guardrails for Claude Code's git and GitHub CLI operations. Blocks pushes and gh
write commands targeting repos you don't own, warns when editing directly on main/master,
and nudges toward committing after idle periods. The design philosophy is guardrails, not
gates — biased toward blocking suspicious operations rather than letting them through.
Claude can always run a command manually if a block is incorrect; it cannot undo a push to
upstream.
Threat model: hooks vs. sandbox
These guardrails enforce policy at the Claude Code level. They run as PreToolUse
hooks — evaluated before a command executes — and guard against accidental self-harm: an
errant git push, a gh write to a repo you don't own, an edit landing straight on main.
They decide whether an operation is allowed to start.
They do not provide OS isolation. A hook cannot contain a process it has already
allowed — once git push or a build script is running, nothing here stops it from reaching
the filesystem or network. Guardrails are the policy layer; an OS sandbox is the
containment layer, and the two are complementary rather than interchangeable.
For unattended or low-supervision runs, pair these guardrails with real isolation:
--dangerously-skip-permissions MUST run inside a container/VM or under
@anthropic-ai/sandbox-runtime, which wraps
the entire Claude Code process in OS-level filesystem and network boundaries.- Auto mode keeps permission prompts, but still benefits from an isolation boundary as
defense-in-depth — containment limits the blast radius if a prompt is mis-approved.
A sandbox is OS-enforced but not a complete boundary,
and these guardrails are policy-only. Use both for unattended work; neither replaces the other.
Hooks
guard-push-remote.sh
Guards: git push to remotes you don't own.
Fires: PreToolUse on Bash.
How it works:
- Resolves the actual push target URL before the command executes. For bare
git push,
follows branch tracking config to find the remote. For explicit git push <remote>,
resolves that remote's push URL.
- Checks the resolved URL against
GIT_GUARDRAILS_ALLOWED_OWNERS using both HTTPS and
SSH GitHub URL patterns.
- Blocks batch commands containing multiple
git push calls or loop constructs — these
cannot be safely resolved statically.
- Partially resolves
cd DIR && git push by extracting the leading cd target.
Config read:
GIT_GUARDRAILS_ALLOWED_OWNERS — REQUIRED. If unset, all pushes are blocked.
guard-gh-write.sh
Guards: gh CLI write operations to repos you don't own.
Fires: PreToolUse on Bash.
How it works:
- Detects write operations across three patterns:
gh <resource> <write-action> where write actions include create, merge, close,
comment, edit, delete, transfer, archive, rename, review, reopen,
ready, lock, unlockgh api with explicit -X POST|PUT|PATCH|DELETEgh api with field flags (-f, -F, --field, --raw-field) indicating an
implicit POST
- Resolves the target repo in priority order: explicit
-R/--repo flag > gh repo create positional arg > gh api path > git remotes.
- Fork-aware: when the CWD has an
upstream remote, resolution is ambiguous (is the
target the fork or the parent?). Requires -R to disambiguate.
- Allows operations targeting the fork's parent repo when
-R is explicitly provided.
- Uses AST-based loop detection via
bash-parser (Node.js) to distinguish real shell
loops from loop keywords inside string arguments (--body content, python3 -c
strings, heredocs). Falls back to regex if the parser chokes on exotic syntax.
Config read:
GIT_GUARDRAILS_ALLOWED_OWNERS — REQUIRED. If unset, all gh writes are blocked.GIT_GUARDRAILS_ALLOWED_REPOS — Optional. Space-separated owner/repo pairs for
repos you collaborate on but don't own.
warn-main-branch.sh
Guards: Accidental edits directly on main/master.
Fires: PreToolUse on Edit and Write.
How it works:
- Checks the current git branch. If it is
main or master, emits a one-time advisory
asking whether the work should be on a feature branch instead.
- Uses a per-repo marker file in
/tmp to fire at most once per session.
- Advisory only — exits 0, never blocks.
Config read: None.
check-idle-return.sh
Guards: Uncommitted work after periods of inactivity.
Fires: PreToolUse on Edit and Write.
How it works:
