git-guardrails-claude-code

Overview of git-guardrails-claude-code skill

The git-guardrails-claude-code skill helps Claude Code refuse a short list of destructive Git commands before they run. Its real job is simple: add a safety layer so an AI coding session cannot casually git push, git reset --hard, git clean -f, delete branches with git branch -D, or wipe working tree changes with git checkout . or git restore ..

Who should use git-guardrails-claude-code

This skill is best for people who:

• use Claude Code directly against real repositories
• want AI assistance but do not want it to perform irreversible Git actions
• work in shared repos, production repos, or client codebases
• prefer local enforcement over “please be careful” prompting

If your main concern is accidental code destruction or unauthorized pushes during an agent session, git-guardrails-claude-code is a strong fit.

What makes this different from a normal prompt

A normal prompt can ask Claude not to run risky commands, but prompts are soft guidance. git-guardrails-claude-code uses a PreToolUse hook, so the restriction lives in Claude Code’s execution path instead of only in the conversation. That is the main differentiator and the main reason to install it.

What it actually blocks

The bundled shell script checks incoming Bash commands and blocks patterns including:

• git push
• git reset --hard
• git clean -f
• git clean -fd
• git branch -D
• git checkout .
• git restore .
• force-push related matches such as push --force

The block message tells Claude it does not have authority to use that command.

What this skill does not do

git-guardrails-claude-code is not a full Git policy engine. It does not:

• review commit quality
• require approvals
• distinguish safe vs unsafe push destinations
• understand repository-specific branching rules
• protect commands outside the listed patterns unless you edit the script

That matters for adoption: this is a focused guardrail, not comprehensive governance.

How to Use git-guardrails-claude-code skill

Start with the scope decision first

The first practical choice in the upstream skill is whether to install the guardrail:

• for this project only in .claude/settings.json, or
• for all projects in ~/.claude/settings.json

This decision changes where you copy the script and how broadly the block applies. For most teams, project-level install is safer for testing. Global install makes sense once you know you want the same Git restrictions everywhere.

Read these files first

You can understand almost everything important by reading:

1. SKILL.md
2. scripts/block-dangerous-git.sh

That reading order is useful because SKILL.md explains the hook wiring, while scripts/block-dangerous-git.sh shows the exact blocked command patterns. If you care about false positives or gaps, the script matters more than the prose.

Install context for git-guardrails-claude-code

The git-guardrails-claude-code install process is mostly manual setup inside Claude Code’s hook system:

1. copy the shell script into a hooks directory
2. make it executable
3. register it under PreToolUse for the Bash matcher

The repository path for the source script is:

scripts/block-dangerous-git.sh

Target locations are:

• project scope: .claude/hooks/block-dangerous-git.sh
• global scope: ~/.claude/hooks/block-dangerous-git.sh

Then make it executable:

chmod +x .claude/hooks/block-dangerous-git.sh

or for global scope:

chmod +x ~/.claude/hooks/block-dangerous-git.sh

Add the Claude Code hook correctly

For project scope, the skill shows a PreToolUse hook in .claude/settings.json that runs the copied script using "$CLAUDE_PROJECT_DIR".

The key wiring points are:

• hook event: PreToolUse
• matcher: Bash
• hook type: command
• command: path to block-dangerous-git.sh

If this hook is not registered under PreToolUse, the script will exist but never intercept commands.

How the script works in practice

The shell script reads tool input from standard input, extracts .tool_input.command using jq, and checks the command against a small array of dangerous patterns with grep -qE.

That means adoption blockers are straightforward:

• jq must be available in the environment
• the command path in settings must be valid
• the script must be executable
• Claude Code must actually be invoking Bash tool calls through the hook system

If any of those pieces fail, the protection silently becomes weaker than you think.

What input the skill needs from you

The upstream skill itself needs very little context, but a good git-guardrails-claude-code usage flow starts with these decisions:

• project-only or global
• whether the default blocked list is enough
• whether your team also wants to block extra commands such as git tag -d, git rebase --abort, or remote-specific pushes
• whether users still need a documented manual escalation path for legitimate pushes

Without those answers, installation is easy but policy fit may be poor.

Turn a rough goal into a strong prompt

Weak prompt:

• “Set up git guardrails.”

Stronger prompt:

• “Install git-guardrails-claude-code for this project only. Copy the hook script into .claude/hooks/, make it executable, update .claude/settings.json with a PreToolUse hook for Bash, and then show me the exact blocked Git patterns from the script.”

Why this is better:

• it defines scope
• it specifies the destination
• it requests both setup and verification
• it reduces the chance Claude improvises a different hook structure

A good first-run workflow

A practical git-guardrails-claude-code guide looks like this:

1. choose project vs global scope
2. inspect scripts/block-dangerous-git.sh
3. copy the script to the target hooks directory
4. chmod +x the copied file
5. wire the PreToolUse hook in the correct settings file
6. test with a harmless simulation or an obviously blocked command in a safe repo
7. decide whether to customize patterns

This order matters because it lets you verify the actual enforcement list before rolling it out broadly.

How to validate the install

Do not stop at “the file exists.” Validate behavior:

• confirm the settings file path is the one Claude Code is using
• confirm the hook command points to the copied script, not the repository source path
• trigger a blocked pattern in a disposable repo
• check that Claude receives a denial instead of running the command

For this skill, behavioral verification is more important than visual verification.

Best fit for Git workflows

git-guardrails-claude-code for Git Workflows is especially useful when your preferred AI workflow is:

• let Claude edit files freely
• let Claude inspect diffs and status
• keep branch deletion, force push, hard reset, and cleanup commands under explicit human control

That split works well because it preserves AI productivity for coding tasks while keeping irreversible repository actions manual.

When to customize the script

The default list is intentionally narrow. Customize scripts/block-dangerous-git.sh if:

• your team treats git push as acceptable but wants only --force blocked
• you also want to block git commit --amend
• your workflow includes sensitive branch deletion patterns
• you want different rules per repository

The main tradeoff is simplicity vs precision. The stock script is easy to audit; a heavily customized one needs more testing.

git-guardrails-claude-code skill FAQ

Is git-guardrails-claude-code good for beginners

Yes, if the beginner is already using Claude Code and wants a safer default around Git. The setup is short, and the concept is easy to understand: intercept Bash tool calls before execution. The only mildly technical parts are JSON hook configuration and shell script permissions.

Is this better than telling Claude “never push”

Yes, for the specific commands it covers. git-guardrails-claude-code converts a conversational rule into an execution-time check. That makes it much more reliable than relying on prompt memory alone.

Does git-guardrails-claude-code block all dangerous Git commands

No. It blocks the explicit patterns in the script. If your risk model includes other commands, you must add them yourself. This is a key boundary of the skill.

Can I use git-guardrails-claude-code globally

Yes. The skill explicitly supports a global install through ~/.claude/settings.json and ~/.claude/hooks/block-dangerous-git.sh. Global install is convenient, but project-only install is easier to test and safer if different repos need different policies.

Will this interfere with normal coding work

Usually not much, if your normal workflow does not expect Claude to push or perform destructive Git cleanup. It is most compatible with a workflow where Claude edits code, runs tests, and prepares changes, while a human handles final Git authority.

When should I not use this skill

Skip git-guardrails-claude-code if:

• you actually want Claude to manage Git end-to-end
• your team needs nuanced allowlists rather than simple pattern blocks
• you cannot rely on shell hooks or jq
• you need organization-wide enforcement beyond local Claude Code configuration

In those cases, this skill may feel too narrow or too local.

How to Improve git-guardrails-claude-code skill

Audit the blocked patterns against your real risks

The fastest way to improve git-guardrails-claude-code is to compare the default pattern list to the Git mistakes you actually care about. Many teams care less about all pushes and more about:

• force pushes
• branch deletion on protected branches
• destructive cleanups on monorepos
• working tree resets during debugging

If your policy differs, edit the pattern array instead of accepting the default blindly.

Provide stronger install instructions to Claude

If you ask Claude to apply this skill, include concrete details:

• scope
• exact destination path
• whether to preserve or merge existing hooks
• whether to print the final JSON file for review
• whether to test the hook after setup

A stronger request is:

• “Install git-guardrails-claude-code only in this repo, merge with any existing .claude/settings.json hooks instead of overwriting them, and show the final settings diff.”

That avoids one of the most common failure modes: replacing existing hook config.

Watch for hook merge mistakes

A realistic problem is not the shell script but the settings file update. If a repository already has hooks configured, careless installation can overwrite them. Ask for:

• a diff, not a blind rewrite
• preservation of existing PreToolUse entries
• explanation of hook ordering if multiple commands run

For many users, this matters more than the blocked command list.

Test false positives and bypasses

Because the script uses pattern matching, you should test:

• legitimate commands that should pass
• blocked commands that should fail
• variants you assume are blocked but may not be
• command strings that contain similar text in unexpected ways

This is the right place to improve confidence in git-guardrails-claude-code usage, especially before global rollout.

Tighten the script only after you see real misses

It is tempting to add many patterns immediately. Resist that unless you have evidence. A short, readable blocklist is easier to trust and maintain. Expand it after observing:

• commands Claude commonly attempts
• commands users consider risky
• patterns that slipped through
• commands that were blocked but should not have been

That keeps the guardrail understandable.

Add a human escalation path

A good operational improvement is to pair the guardrail with a clear rule such as:

• Claude may prepare commits and explain push steps
• a human performs the final push or destructive cleanup manually

This improves the skill because users stop fighting the guardrail and start designing around it.

Revisit whether global or project scope is still right

After initial use, reevaluate scope:

• if the rule works across all repos, move it global
• if some repos need looser Git behavior, keep it project-local
• if teams vary, maintain separate project-level versions of the script

This is one of the simplest ways to improve fit without changing code.

Keep the script readable

If you customize git-guardrails-claude-code, keep the shell script easy to audit. Favor a clear list of patterns and a single error path over clever logic. For a safety control, readability is part of reliability.