SkillAgentSearch skills...

git-guardrails

Install a hook that blocks destructive git commands before an AI agent runs them

Install / Use

npx skills add borghei/Claude-Skills --skill git-guardrails

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

89/100

Supported Platforms

Claude Code

Our assessment of git-guardrails

git-guardrails scores 89/100 on our quality scale, 1706th of 4,698 Development & Engineering skills we index (top 37%).

Its SKILL.md is 14 KB long, well organised into 25 sections with 4 code examples: a thorough specification that gives an agent plenty to work with.

It has 817 GitHub stars, a meaningful sign that others use it.

Substance
30/30
Structure
20/20
Description
12/15
Adoption
12/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so git-guardrails is actively maintained.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-11-10. Automated pattern scan on 2026-11-10. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

git-guardrails compared with similar skills

All 4 of these similar skills score higher than git-guardrails; compare them before choosing.

SkillScoreStarsUpdatedFormat
git-guardrails (this skill)by borghei8981756d agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md
claude-howtoby luongnv8910047.3k2d agoCLAUDE.md

Frequently asked questions

How do I install git-guardrails?
Run npx skills add borghei/Claude-Skills --skill git-guardrails. The install tabs above show the steps for each supported agent.
Which AI agents does git-guardrails work with?
It is written for Claude Code, as a SKILL.md file. Other agents that read the same format can often use it too.
Is git-guardrails safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is git-guardrails still maintained?
The repository was last updated about 2 months ago, so git-guardrails is actively maintained.

name: git-guardrails description: > Install a hook that blocks destructive git commands before an AI agent runs them. Use when an agent force-pushed or ran reset --hard, when adding git safety hooks, or when protecting main from agent pushes. license: MIT + Commons Clause metadata: version: 1.0.0 author: borghei category: engineering domain: developer-tooling updated: 2026-11-08 tags: [git, hooks, claude-code, safety, pretooluse, branch-protection]

Git Guardrails

An agent with shell access can run git reset --hard, git clean -fdx or git push --force as casually as ls, usually while trying to make a failing command pass. This skill installs a PreToolUse hook that reads every Bash call before it runs, parses the git invocations inside it (chains, subshells, bash -c, xargs, git -C), and blocks the destructive ones with exit code 2 and a reason the agent can act on. It ships the hook, an installer that merges into .claude/settings.json without overwriting anything, plain git pre-push and pre-rebase hooks for non-agent callers, and a corpus tester that proves which commands are allowed and which are blocked.

When to use this skill

  • After an incident: an agent discarded uncommitted work, deleted a branch, or force-pushed over a teammate's commits
  • Before giving an agent autonomy: auto-accept mode, background agents, long unattended runs, or several agents in parallel worktrees
  • Protecting shared branches: no direct pushes or rebases on main, release/*, production
  • Auditing an existing guardrail: run its hook against the corpus to see what it actually catches
  • Rolling guardrails out to a team: one committed project-scope hook plus a CI-runnable test

Not for server-side branch protection (configure that in your Git host) or for general command sandboxing; this guards git specifically.

Clarify First

The install scope and the protected-branch list decide what gets blocked, so settle them before installing. When one is missing or vague and would change the result, ask about it; when it wouldn't, use the default and say so.

  • Scope: project scope (<repo>/.claude/settings.json, committed, applies to every contributor's agent) or user scope (~/.claude/settings.json, every repo on this machine). The default is project scope, because team rules belong in version control.
  • Protected branches: the default list is main, master, develop, trunk, production, prod, release/*. Repos with stable, staging or deploy/* need a policy file, or pushes to those branches pass.
  • Force-with-lease on feature branches: allowed by default so an agent can update its own rebased PR. Teams that forbid any history rewrite after push should turn it off.
  • Non-agent callers: if release scripts, IDEs or humans also need the push rules, add the plain git hooks (--git-hooks).

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, install at project scope with defaults and state your assumptions at the top.

Quick Start

# 1. See exactly what would change (writes nothing)
python3 engineering/git-guardrails/scripts/install_guardrails.py --project . --dry-run

# 2. Install hook + policy file + plain git hooks
python3 engineering/git-guardrails/scripts/install_guardrails.py --project . --policy --git-hooks

# 3. Prove it: run the corpus through the installed hook
python3 engineering/git-guardrails/scripts/guardrail_test.py --hook .claude/hooks/git_guardrails_hook.py

Restart the Claude Code session afterwards; settings are read at session start.

Tools Overview

| Tool | Purpose | Exit codes | |------|---------|------------| | scripts/install_guardrails.py | Copy the hook into .claude/hooks/, merge one PreToolUse entry into settings.json, optionally add policy and git hooks. --dry-run prints a unified diff | 0 installed or already installed, 1 a conflict was left untouched, 2 usage error or invalid settings (nothing written) | | scripts/guardrail_test.py | Pipe each corpus command to a hook as a real PreToolUse payload; report allow/block and rule id per case. --command tests one command | 0 all cases matched, 1 any mismatch or reasonless block, 2 usage error | | assets/git_guardrails_hook.py | The hook itself. Stdin JSON in; exit 0 allow or exit 2 + stderr reason. --check "<cmd>" for manual use | 0 allow, 2 block | | assets/pre-push, assets/pre-rebase | Plain git hooks: force/non-fast-forward pushes, protected deletes, rebases of protected branches | 0 continue, 1 abort |

All tools take --format text|json (except the hooks, whose output format is fixed by their callers).

Workflows

Workflow 1: Install at project scope [RECOMMENDED]

  1. Confirm the protected-branch list with the user. If it differs from the defaults, the installer's --policy copies assets/sample_guardrail_policy.json to .claude/git-guardrails.json; edit that file.
  2. Dry-run the installer and read the diff. Verify that the only change to settings.json is one appended PreToolUse entry.
  3. Install for real. A pre-existing settings.json is backed up to settings.json.bak.
  4. Run the tester against the installed copy. It must pass every case before you call the install done.
  5. Commit .claude/settings.json, .claude/hooks/git_guardrails_hook.py and the policy file so every contributor's agent gets the same rules.
python3 engineering/git-guardrails/scripts/install_guardrails.py --project . --policy --format json
python3 engineering/git-guardrails/scripts/guardrail_test.py \
  --hook .claude/hooks/git_guardrails_hook.py --policy .claude/git-guardrails.json

The installer never edits an existing hook entry. A settings.json that is not valid JSON stops the run with exit 2 and nothing written: fix the JSON by hand first. Re-running is safe: the second run reports unchanged.

Workflow 2: Add the plain git layer

  1. Run the installer with --git-hooks. It installs pre-push and pre-rebase into .git/hooks/ only where no hook exists.
  2. If it reports conflict-foreign, a hook from another tool (husky, pre-commit, lefthook) is already there. Chain ours from it instead of replacing it; references/hook-mechanics.md has the snippet.
  3. Set protected branches in git config so the shell hooks share the policy:
git config --add guardrails.protected main
git config --add guardrails.protected 'release/*'
git config guardrails.blockDirectPush true

Git has no hook for reset, clean or branch -D. The git layer covers pushes and rebases from any caller; the Claude Code hook covers everything the agent types. Use both.

Workflow 3: Validate or extend the rules

  1. Reproduce the command the agent actually ran (or the one that was wrongly blocked) with --command and --branch.
  2. Add it to a corpus copy as a case with expect and, for blocks, the rule id. Add the closest harmless neighbour as an allow case too.
  3. Change the policy (disabled_rules, protected_branches, extra_block_regex) or the hook, then re-run the full corpus. The corpus is the regression suite: no rule change ships with a failing case.
python3 engineering/git-guardrails/scripts/guardrail_test.py \
  --command "git push origin HEAD" --branch main
python3 engineering/git-guardrails/scripts/guardrail_test.py \
  --corpus engineering/git-guardrails/assets/sample_command_corpus.json --format json

Workflow 4: Audit somebody else's guardrail

  1. Point --hook at their script. It must speak the same contract (stdin JSON, exit 2 to block).
  2. Run the bundled 79-case corpus. Mismatches show which shapes it misses, typically cd x && git reset --hard, bash -c "...", -fdx flag clusters, or git -C.
  3. Check for exit-1 blocks: the tester reports any exit code other than 0 or 2 as an error, because Claude Code treats exit 1 as "warn and run anyway".

What gets blocked

Defaults below; references/rule-catalog.md has every rule with the allowed cousins, safe alternatives and recovery steps.

| Loss class | Rules | |------------|-------| | Uncommitted work (no recovery) | reset --hard, clean -f*, checkout . / checkout -f, restore ., switch --discard-changes, worktree remove --force | | Local history (reflog recovers) | branch -D, branch -M/-C, stash clear, update-ref -d | | Shared history | push --force / +ref, lease pushes to protected branches, push to protected, push --delete / :ref, push --mirror, rebase of a protected branch, filter-branch, filter-repo | | Safety net | reflog expire --expire=now, gc --prune=now, --no-verify |

Design decisions

  • [PROVEN] Parse, don't grep. grep "push --force" both misses push -f origin x and blocks echo "never push --force". The hook tokenises with shlex, splits on shell operators, unwraps sudo/env/xargs/bash -c, and reads git's own global options before the subcommand.
  • [PROVEN] Exit 2, never exit 1. Exit 1 is a non-blocking error in Claude Code: the command still runs. The hook has no path that raises.
  • [RECOMMENDED] Allow --force-with-lease on feature branches. Blocking it pushes agents toward worse workarounds; the lease already refuses when someone else pushed.
  • [RECOMMENDED] Block on the current branch, not just explicit refspecs. A bare git push on main is the most common accidental protected push.
  • [RECOMMENDED] Fail open on unparseable input, fail closed on a broken policy. Non-Bash payloads exit 0 so the hook never wedges the session; an unreadable policy file falls back to the strict defaults.

Anti-Patterns

The Grep Guardrail

Mistake: Blocking on grep -E "push.*--force|reset --hard" over the raw command. Why it happens: It is a one-liner and catches the exact command from the incident. Instead: Parse the command. Run the corpus against the grep version: it misses -f, -fdx clusters and git -C, and blocks grep/echo lines that only mention the words. A guardrail with false positives gets disabled within a week.

The Exit-1 Block

Mistake: Writing the hook to exit 1 (or letting it crash) when it means to block. Why it happens: Exit 1 means failure everywhere else, and a traceback feels like a refusal. Instead: Block with exit 2 and a stderr reason. Exit 1 only warns the user and the command runs anyway. The tester flags any exit code other than 0 or 2.

The Overwritten Settings File

Mistake: Writing a fresh .claude/settings.json that contains only the guardrail hook. Why it happens: Examples show a complete file, and copying it is faster than merging. Instead: Merge. The installer appends one entry, keeps permissions, env and every other hook, backs up the old file, and refuses to touch invalid JSON. Always dry-run first and read the diff.

The Workaround Invitation

Mistake: A block message that only says "command not allowed". Why it happens: The author thinks of the hook as a filter, not as a message to the model. Instead: Say why it is dangerous and what to do next: stop, explain, hand it to the human. Without that line, models reach for the next closest destructive command.

The Hook-Only Strategy

Mistake: Treating the client hook as the protection for main. Why it happens: It visibly blocks the agent, so it feels complete. Instead: Keep server-side branch protection on (no force push, no deletion, required reviews). Client hooks catch mistakes early; only server rules cannot be skipped with --no-verify, an alias or a script.

Verification Checklist

  • [ ] Dry-run diff shows one appended PreToolUse entry and nothing else changed
  • [ ] guardrail_test.py passes against the installed copy, with the pro

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars817
CategoryDevelopment
Updated1mo ago
Forks141

Languages

HTML

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium