VibeGuard

Stop Claude Code and Codex from making the same expensive mistakes twice.

Chinese Docs · Rule Reference · Contributing

VibeGuard adds native rules + real-time hooks + static guards to catch what AI coding agents get wrong — before it reaches your codebase:

• Duplicate files and reinvented modules
• Invented APIs, fake libraries, and hardcoded placeholder values
• Dangerous shell/git commands (rm -rf, push --force, reset --hard)
• Analysis paralysis and unverified "I'm done" claims
• Silent exception swallowing and Any-type abuse
• AI-slop patterns flagged on every commit

Works with Claude Code and Codex CLI.

Install in 30 seconds

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

Open a new Claude Code or Codex session. Run bash ~/vibeguard/setup.sh --check to verify.

What you actually get

Product Boundaries

VibeGuard has two layers:

If these surfaces disagree, treat the Core contract as authoritative first, then update workflow/docs surfaces to match it.

For repository layout ownership, see Directory Map.

What it looks like in practice

You:  "Add a login endpoint"

AI:   → tries to create auth_service.py
      ✗ VibeGuard blocks — duplicate of existing auth.py, search first

      → tries to import `flask-auth-magic`
      ✗ VibeGuard blocks — non-existent library, verify before adding

      → hardcodes JWT secret as "your-secret-key"
      ✗ VibeGuard flags — use env var or secret manager

      → runs `git push --force`
      ✗ VibeGuard denies — suggests `--force-with-lease`

      → keeps reading files without acting
      ⚠ VibeGuard escalates — force a concrete next step or report blocker

      → claims done without verifying
      ⚠ VibeGuard gates — run build/test before finishing

Every interception returns a fix instruction, not just a failure — so the agent can self-correct.

Re-record your own demo: see docs/assets/README.md (one command via asciinema + agg).

Who this is for

Use VibeGuard if you:

• Use Claude Code or Codex regularly
• Have seen duplicate files, fake APIs, over-engineering, or unverified "done" claims
• Want mechanical enforcement, not just prompt guidelines

It may be overkill if you only use AI occasionally or don't want hook-level interception.

Inspired by OpenAI Harness Engineering and Stripe Minions. Fully implements all 5 Harness Golden Principles.

How It Works

Rule Injection (active from session start)

The native rule set in rules/claude-rules/ is installed to Claude Code's native rules system (~/.claude/rules/vibeguard/), directly influencing AI reasoning. Plus a 7-layer constraint index injected into ~/.claude/CLAUDE.md:

Rules use negative constraints ("X does not exist") to implicitly guide AI, which is often more effective than positive descriptions.

Canonical references for this contract:

• Install/runtime contract: schemas/install-modules.json
• Native rule source: rules/claude-rules/
• Public summary of current rule surface: docs/rule-reference.md

Hooks — Real-Time Interception

Most hooks trigger automatically during AI operations. skills-loader remains an optional manual hook, and Codex currently deploys only Bash/Stop hook events:

Static Guards — Run Anytime

Representative standalone checks you can run on any project. The complete inventory lives in docs/rule-reference.md.

# Universal
bash ~/vibeguard/guards/universal/check_code_slop.sh /path/to/project     # AI code slop
python3 ~/vibeguard/guards/universal/check_dependency_layers.py /path      # dependency direction
python3 ~/vibeguard/guards/universal/check_circular_deps.py /path          # circular deps
bash ~/vibeguard/guards/universal/check_test_integrity.sh /path            # test shadowing / integrity issues

# Rust
bash ~/vibeguard/guards/rust/check_unwrap_in_prod.sh /path                 # unwrap/expect in prod
bash ~/vibeguard/guards/rust/check_nested_locks.sh /path                   # deadlock risk
bash ~/vibeguard/guards/rust/check_declaration_execution_gap.sh /path      # declared but not wired
bash ~/vibeguard/guards/rust/check_duplicate_types.sh /path                # duplicate type definitions
bash ~/vibeguard/guards/rust/check_semantic_effect.sh /path                # semantic side effects
bash ~/vibeguard/guards/rust/check_single_source_of_truth.sh /path         # single source of truth
bash ~/vibeguard/guards/rust/check_taste_invariants.sh /path               # taste/style invariants
bash ~/vibeguard/guards/rust/check_workspace_consistency.sh /path          # workspace dep consistency

# Go
bash ~/vibeguard/guards/go/check_error_handling.sh /path                   # unchecked errors
bash ~/vibeguard/guards/go/check_goroutine_leak.sh /path                   # goroutine leaks
bash ~/vibeguard/guards/go/check_defer_in_loop.sh /path                    # defer in loop

# TypeScript
bash ~/vibeguard/guards/typescript/check_any_abuse.sh /path                # any type abuse
bash ~/vibeguard/guards/typescript/check_console_residual.sh /path         # console.log residue
bash ~/vibeguard/guards/typescript/check_component_duplication.sh /path    # duplicated component files
bash ~/vibeguard/guards/typescript/check_duplicate_constants.sh /path      # repeated constant definitions

# Python
python3 ~/vibeguard/guards/python/check_duplicates.py /path                # duplicate functions/classes/protocols
python3 ~/vibeguard/guards/python/check_naming_convention.py /path         # camelCase mix
python3 ~/vibeguard/guards/python/check_dead_shims.py /path                # dead re-export shims

Slash Commands

10 custom commands covering the full development lifecycle. Shortcuts: /vg:pf /vg:gc /vg:ck /vg:lrn.

Complexity Routing

Multi-Agent Dispatch

14 built-in agent prompts (13 specialists + 1 dispatcher) with automatic routing:

Observability

bash ~/vibeguard/scripts/quality-grader.sh              # Quality grade (A/B/C/D)
bash ~/vibeguard/scripts/stats.sh                       # Hook trigger stats (7 days)
bash ~/vibeguard/scripts/hook-health.sh 24              # Hook health snapshot
bash ~/vibeguard/scripts/metrics/metrics-exporter.sh    # Prometheus metrics export
bash ~/vibeguard/scripts/verify/doc-freshness-check.sh  # Rule-guard coverage check

Learning System

Closed-loop learning evolves defenses from mistakes:

Mode A — Defensive

/vibeguard:learn <error description>

Analyzes root cause (5-Why) → generates a new guard/hook/rule → verifies detection → the same class of error should not recur.

Mode B — Accumulative

/vibeguard:learn extract

Extracts non-obvious solutions as structured Skill files for future reuse.

Installation

Profiles and languages

# Profiles
bash ~/vibeguard/setup.sh                              # Install (default: core profile)
bash ~/vibeguard/setup.sh --profile minimal           # Minimal: pre-hooks only (lightweight)
bash ~/vibeguard/setup.sh --profile full              # Full: adds Stop Gate + Build Check + Pre-Commit
bash ~/vibeguard/setup.sh --profile strict            # Strict: same hook set as full, for stricter runtime policy

# Language selection (only install rules/guards for specified languages)
bash ~/vibeguard/setup.sh --languages rust,python
bash ~/vibeguard/setup.sh --profile full --languages rust,typescript

# Verify / Uninstall
bash ~/vibeguard/setup.sh --check                     # Verify installation
bash ~/vibeguard/setup.sh --clean                     # Uninstall

Codex Integration

VibeGuard deploys hooks and skills to both Claude Code and Codex CLI.

Hooks live in ~/.codex/hooks.json (requires codex_hooks = true in config.toml):

Note: Codex PreToolUse/PostToolUse currently only supports the Bash matcher. Edit/Write guards (pre-edit, pre-write, post-edit, post-write) and analysis-paralysis are not deployable on the native Codex CLI hook path.

Codex hook command names are namespaced as vibeguard-*.sh to avoid collisions with other toolchains sharing ~/.codex/hooks.json. Output format differences are handled by the run-hook-codex.sh wrapper (Claude Code decision:block → Codex permissionDecision:deny). When a hook suggests updatedInput, the Codex CLI wrapper cannot apply it automatically, so VibeGuard emits an explicit note with the suggested replacement command instead of silently dropping it.

App-server wrapper (Symphony-style orchestrators):

python3 ~/vibeguard/scripts/codex/app_server_wrapper.py --codex-command "codex app-server"

• --strategy vibeguard (default): applies pre/stop/post gates externally
• --strategy noop: pure pass-through for debugging
• App-server wrapper scope today: Bash approval interception + post-turn stop/build feedback with explicit thread/session/turn propagation
• Still unsupported on app-server path: pre-edit, pre-write, post-edit, post-write, analysis-paralysis

Use with any project

Project Bootstrap

Bootstrap another repository with project-specific guidance and the pre-commit wrapper:

bash ~/vibeguard/scripts/project-init.sh /path/to/project

Local Contract Gate (contributors)

Run stable contract checks locally before pushing, or wire them as a pre-commit hook:

bash scripts/local-contract-check.sh          # run the full local gate
bash scripts/install-pre-commit-hook.sh       # install as git pre-commit hook

See CONTRIBUTING.md for the local-vs-CI split and the --quick flag.

Custom Rules

Add your own rules to ~/.vibeguard/user-rules/. Any .md files placed there are automatically installed to ~/.claude/rules/vibeguard/custom/ on the next setup run. Format: standard Claude Code rule files with YAML frontmatter.

Design Principles

Known Issues

Guard scripts rely heavily on pattern matching (grep/awk or lightweight AST helpers), which means false positives can still happen in some scenarios.

• Known False Positives — identified false positive scenarios, fixes, and lessons learned

Key lessons:

• grep is not an AST parser — nested scopes and multi-block structures need language-aware tools
• Guard fix messages are consumed by AI agents — an imprecise fix hint can itself trigger unnecessary edits
• Project type awareness matters — CLI/Web/MCP/Library codebases may need different acceptable patterns for the same language rule

Documentation

References

• OpenAI Harness Engineering
• Stripe Minions
• Anthropic: Effective Harnesses for Long-Running Agents

Chinese Documentation →