starlight · vibeguard v1.1

# Stop the slop.
Before the commit.

Native rules + real-time hooks + static guards to catch what AI coding agents get wrong — before it reaches your codebase. Duplicate files, invented APIs, dangerous shell commands, unverified "I'm done" claims. Blocked, warned, or surfaced with a fix.

$ git clone ... && bash ~/vibeguard/setup.sh --yes
how it works →
126
native rules
7
constraint layers
12
Codex hook entries
2
agents supported
why vibeguard

## Prompt guidelines don't stop bad actions.

#### without vibeguard

- Agent creates `utils_v2.py` next to `utils.py` — duplicate files pile up.
- Agent invents `user.fullName` that never existed on the model.
- Agent runs `git push --force` on main.
- Agent claims "tests pass" without running them.
- Every mistake is a lesson you pay for once per session.

#### with vibeguard

- L1 search-before-create blocks duplicates at write time.
- L4 data-integrity rejects undeclared APIs and fields.
- pre-bash-guard suggests `--force-with-lease`.
- W-03 verification gate demands fresh command output.
- `/vibeguard:learn` turns each mistake into a new guard.

### Mechanical enforcement

Hooks block bad actions at the source. Not prompt guidelines the model can forget.

### Every error is a fix

Interceptions return OBSERVATION → FIX → WHY. The agent self-corrects in one turn.

### Mistake → defense

Repeated errors become new guards via `/vibeguard:learn`. The system gets stricter over time.

three-layer defense

## Rules bias. Hooks block. Guards scan.

layer | what it does
--- | ---
Native rules | 126 constraints auto-loaded into CLAUDE.md / AGENTS.md. Bias the model away from bad decisions before it acts.
Runtime hooks | PreToolUse / PostToolUse intercept writes, bash, edits. Block, warn, or surface fix instructions in real time.
Static guards | Project scans for duplicate files, slop patterns, structural issues. Run via `/vibeguard:check`.
Slash commands | `/vibeguard:preflight`, `:review`, `:check`, `:learn` — workflows for each phase of the loop.
Learning loop | Repeated mistakes surface as candidate rules. Reviewed, then compiled into the native rule set.
Observability | Metrics, logs, and health checks for every interception. You see what was blocked and why.

a real interception

## Blocked with a fix, not just a no.

hook · pre-bash-guard

    ┌─ VibeGuard ─────────────────────────────────────────┐
    ✗ blocked  pre-bash-guard

      → command:  git push --force origin main
      → rule:     L7 · commit discipline · W-force-destructive
      → reason:   destructive overwrite on protected ref

      ⚠  fix
        use git push --force-with-lease instead
        or resolve upstream locally before pushing

    └─────────────────────────────────────────────────────┘
    agent: retrying with --force-with-lease

7-layer constraint index

## Seven rules. Injected at session start.

L1
Search before create
No similar-file pattern. Extend existing code first.
L2
Naming conventions
snake_case internally, camelCase at API boundary. No aliases.
L3
Quality baseline
No silent exception swallowing. No Any-typed public methods.
L4
Data integrity
No data = blank. No undeclared API or field exists.
L5
Minimal changes
Do what was asked. No "easy improvements" on the side.
L6
Process gates
1–2 files direct · 3–5 preflight · 6+ interview → spec.
L7
Commit discipline
No AI tags. No force push. No secrets in commits.
+
U · RS · TS · SEC · W
Language and security rule families extend the seven core layers.
get started

## Install in 30 seconds.

    $ git clone https://github.com/majiayu000/vibeguard.git ~/vibeguard
    $ bash ~/vibeguard/setup.sh --yes

Works with Claude Code and Codex CLI · MIT licensed · no telemetry