code-guard

A dependency-free Git quality gate that catches AI-generated code smell before it reaches a commit.

Generic variable names, commented-out dead code, swallowed exceptions, placeholder text left over from an LLM ("TODO: implement", "here's the complete solution") — code-guard scans exactly what's staged or about to be pushed, blocks the ones that match, and hands the decision to a human instead of silently passing or silently blocking. Full rule reference: SKILL.md. The standard itself, in prose: RULEBOOK.md.

Why

Most linters check style. code-guard checks for a different failure mode: code that's syntactically fine but reads like nobody reviewed it — a data variable three scopes deep, a catch (e) {} that eats a real error, a docstring that says "Certainly! Here's the updated function". None of that is a syntax error. All of it is a code-review red flag, and all of it is exactly what a language model produces under time pressure.

Install

One command (Node ≥ 16, any OS):

npx --allow-git=all github:Enes-Balaban17/code-guard

This copies the repo into your project at .agents/skills/code-guard/ and runs the hook installer for you. The --allow-git=all flag is required on npm 12+, which disables installing straight from a git URL by default (EALLOWGIT) — the flag only affects this one invocation, nothing is changed globally. No npm account, no npm publish, no registry involved: it clones straight from this repo.

Or by hand, if you'd rather not run an installer script: clone/download this repo's contents into your project at .agents/skills/code-guard/, then:

python .agents/skills/code-guard/scripts/install_code_guard_hooks.py

Either way — no pip install, no npm install. code_guard.py is pure Python standard library. This sets git config core.hooksPath .agents/skills/code-guard/hooks, so every git commit and git push now runs through the gate automatically.

Use it directly

python .agents/skills/code-guard/scripts/code_guard.py --staged      # what's about to be committed
python .agents/skills/code-guard/scripts/code_guard.py --all         # the whole repo
python .agents/skills/code-guard/scripts/code_guard.py --files a.js b.py

Inside Claude Code: /code-guard.

Result

• Exit 0 → PASS · 1 → FAIL (commit/push aborted) · 2 → runtime error.
• Report: .code-guard/reports/code-guard-report-*.md.

Human-in-the-Loop override

After a FAIL, a deliberate bypass:

CODE_GUARD_OVERRIDE=1 git commit -m "feat(x): ..."     # Bash
$env:CODE_GUARD_OVERRIDE=1; git commit -m "feat(x): ..."  # PowerShell

A direct push to main/master is rejected even with the override — a passing, reviewed PR is required (see RULEBOOK.md #6).

Suppressing a single finding

A real API boundary (an MCP tool, a REST handler) sometimes needs more than 3 parameters legitimately. Suppress that one finding inline:

def ask_model(model, prompt, system="", provider="",  # code-guard: allow CC-002
              temperature=0.7, max_tokens=512):

Uninstall

python .agents/skills/code-guard/scripts/install_code_guard_hooks.py --uninstall

Dependencies

Python 3.8+ standard library only. Nothing else.

License

MIT — see LICENSE.