vc-guard

A guard rail for vibe coding. Claude can't sneak code past you.

vc-guard is a Claude Code plugin that keeps a human in the loop:

• Nothing lands without review. git push / git merge / gh pr merge are hard-blocked, and git commit is ack-gated — blocked until you review the exact diff and run vc-guard ack. Any later edit re-locks it.
• Makes you review and understand every change first. From the first turn the agent is told to walk you through what it changed and why; a review skill runs a proper, file-by-file, comprehension-checked review; and every file the agent writes is logged so nothing slips by.

The point: with AI writing most of the code, the risky part is landing changes you haven't actually understood. vc-guard turns "just commit it" into a deliberate, reviewed step.

Install

/plugin marketplace add Dales24/vc-guard
/plugin install vc-guard@vc-guard

(or point the marketplace at a local clone: /plugin marketplace add /path/to/vc-guard)

Start a new session. Test it: ask Claude to commit something — it'll be blocked with an explanation, and you'll see the guard's note in the session context.

How it works

Piece	Type	What it does
hooks/guard.py	PreToolUse (Bash) hook	Hard-denies git push / git merge / gh pr merge. Ack-gates git commit (allowed only when the current diff is acknowledged). Read-only git (status, diff, log, add) passes through.
hooks/post_edit.py	PostToolUse (Edit/Write) hook	Logs every file the agent writes, so the block message and review skill can show exactly what changed.
hooks/session_notice.py	SessionStart hook	Injects the rules so the agent explains changes for review and never tries to auto-commit or ack.
skills/review/SKILL.md	Skill	Walks you through every change — what/why/watch-outs + an "understand check" — then tells you to vc-guard ack and hands you the commit commands.
bin/vc-guard	CLI (you run it)	status · ack · reset.

The blocker is careful about intent: it finds git's real subcommand (skipping global options like git -C repo commit), splits chained commands (a && git push), sees through wrapper prefixes (sudo/env/VAR=1 git push), and won't trip on things like a branch named commit or echo git commit.

The ack gate (enforced review)

A commit is blocked until you acknowledge the exact changes:

vc-guard status        # what changed, and whether it's acknowledged yet
# → review the diff (or run the `review` skill in Claude)
vc-guard ack           # unlock a commit of THIS exact diff

The ack is a fingerprint of the current diff (tracked and untracked file contents). Edit anything afterward and the fingerprint changes, so the ack expires and you review again — you can't accidentally commit code you haven't looked at. A successful commit consumes the ack.

Add the CLI to your shell so vc-guard just works:

alias vc-guard='python3 /path/to/vc-guard/bin/vc-guard'

Layout

vc-guard/
├─ .claude-plugin/
│  ├─ plugin.json          plugin manifest (wires in the hooks)
│  └─ marketplace.json     so it installs via /plugin
├─ hooks/
│  ├─ hooks.json           registers the PreToolUse / PostToolUse / SessionStart hooks
│  ├─ guard.py             the push/merge blocker + commit ack-gate
│  ├─ post_edit.py         logs files the agent writes
│  ├─ session_notice.py    injects the guard's rules each session
│  └─ vcguard_state.py     ack fingerprint + touched-file state (in .git/vc-guard/)
├─ skills/
│  └─ review/SKILL.md      the human review walkthrough
├─ bin/
│  └─ vc-guard             CLI: status / ack / reset
└─ tests/
   ├─ test_guard.py        unit tests for the command blocker
   └─ test_state.py        integration tests for the ack gate

Test

python3 -m unittest discover -s tests

Covers blocked commands (commit/push/merge, chained, global options, gh pr merge) and allowed ones (read-only git, a commit-named branch, quoted text).