DEV Community

Boucle
Boucle

Posted on

"branch-guard: Stop Claude Code From Committing to Main"

#claudecode #ai #git #productivity

You gave Claude Code a task. It did the work, then committed directly to main. Now you have untested code on your production branch with no PR review.

branch-guard prevents this by blocking git commit on protected branches.

Install 

curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/branch-guard/install.sh | bash
Enter fullscreen mode Exit fullscreen mode

What it does

branch-guard is a Claude Code hook that runs before every bash command. When it sees git commit on a protected branch, it blocks the command and suggests creating a feature branch instead.

Blocked:

$ git commit -m "fix: update auth" (on main)
→ branch-guard: Direct commit to 'main' is not allowed.
  Suggestion: Create a feature branch first: git checkout -b feature/your-change
Enter fullscreen mode Exit fullscreen mode

Allowed:

$ git commit -m "fix: update auth" (on feature/auth-fix)
→ ✓ proceeds normally

$ git commit --amend (on main)
→ ✓ amending existing commits is allowed
Enter fullscreen mode Exit fullscreen mode

Default protected branches: main, master, production, release.

Configure

Create .branch-guard in your project root to customize:

# Only protect these branches
protect: main
protect: staging
protect: deploy
Enter fullscreen mode Exit fullscreen mode

When a config file exists, it replaces the defaults. So if you only list main and staging, master and production are no longer protected.

Or use an environment variable:

export BRANCH_GUARD_PROTECTED=main,master,staging
Enter fullscreen mode Exit fullscreen mode

Why amend is allowed

git commit --amend modifies the most recent commit rather than creating a new one. If the commit already exists on a protected branch (from a merge, for example), amending it is a normal workflow. branch-guard only blocks new commits.

Works with other hooks

branch-guard complements the other safety hooks:

  • git-safe - blocks destructive git operations (force push, reset --hard)
  • bash-guard - blocks dangerous shell commands (rm -rf, sudo, eval)
  • file-guard - protects sensitive files from modification

Install all of them:

curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- all
Enter fullscreen mode Exit fullscreen mode

Source

GitHub - 35 tests, MIT licensed, ~100 lines of bash.

Top comments (1)

Collapse
 
nyrok profile image
Hamza KONTE •

Hooks as architectural enforcement is the right pattern — the agent can't reason around exit 2. That said, branch-guard solves a symptom. The root cause is usually a missing constraints block in the opening prompt.

If the session prompt explicitly says "always create a feature branch before committing — never commit directly to main or master" as a typed constraint, the agent follows it in the first place. The hook is the catch-all for when that constraint is missing or ignored. Together they're defense in depth: explicit constraints at the prompt layer, hook enforcement at the tool layer.

I built flompt (flompt.dev) to make the constraints block explicit and structured — 12 semantic blocks compiled into Claude-optimized XML, including a dedicated constraints block where rules like branch policy belong. The combination of a well-structured prompt + branch-guard means the hook rarely fires because the agent already knows the rule.

Complements git-safe and the rest of the Boucle toolkit well. Open-source: github.com/Nyrok/flompt — ⭐ if useful.