vibe-safe

For the non-technical contributor: Claude wrote the code. You read the first two lines, it looked fine. The commit message says "update." You accepted "theirs" on all the merge conflicts. The test suite is green because Claude lowered the coverage threshold, not because the tests pass. The API key is in a file you never opened — it won't appear in your diff.

Run this before you commit. It reads your actual git state, not what you assume is in it.

For the developer: Everything above has already happened in your repo. Install this before it happens again.

40 risk categories. Developer-defined contracts. Every flag cites file:line. Claude reads the actual git state — nothing is self-reported.

What it guards against

Install

git clone https://github.com/googlarz/vibe-safe ~/.claude/skills/vibe-safe

Install the pre-commit hook (runs locally on every git commit):

cp ~/.claude/skills/vibe-safe/hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Install CI integration (runs in GitHub Actions — catches --no-verify bypasses):

mkdir -p .github/vibe-safe .github/workflows
cp ~/.claude/skills/vibe-safe/ci/vibe-safe-ci.sh .github/vibe-safe/
cp ~/.claude/skills/vibe-safe/ci/workflow.yml .github/workflows/vibe-safe.yml

Or just run vibe-safe — BEFORE mode installs both automatically.

GitLab CI integration:

mkdir -p .gitlab/vibe-safe
cp ~/.claude/skills/vibe-safe/ci/vibe-safe-ci.sh .gitlab/vibe-safe/

Include the job in your .gitlab-ci.yml:

include:
  - local: '/ci/gitlab-ci.yml'  # or copy the job from ci/gitlab-ci.yml

Set GITLAB_TOKEN in your CI/CD variables (Settings → CI/CD → Variables) to enable MR comment posting.

Bitbucket Pipelines integration:

mkdir -p .bitbucket/vibe-safe
cp ~/.claude/skills/vibe-safe/ci/vibe-safe-ci.sh .bitbucket/vibe-safe/

Merge the step definition from ci/bitbucket-pipelines.yml into your bitbucket-pipelines.yml.

Usage

Just say vibe-safe — Claude auto-detects the right mode from your git state:

No staged changes, describing a task      → BEFORE mode
git diff --staged has content             → COMMIT mode
Unstaged changes present                  → REVIEW mode
"did Claude change more than I asked?"   → SCOPE mode
Commits ahead of main, about to open PR  → PR mode
Conflict markers in any file             → CONFLICT mode
Claude proposed something that feels big → ALARM mode
"what does this flag mean?"              → EXPLAIN mode
Developer reviewing a vibe-coded PR      → REVIEWER mode
Checking whether past commits are clean  → HISTORY mode
.vibesafe exists, repo has evolved       → REFRESH mode

Or invoke directly: vibe-safe commit / vibe-safe explain ssl / vibe-safe reviewer / vibe-safe refresh / etc.

After any session: vibe-safe verify — confirms the session is clean before you walk away.

How it works

Active, not passive. Claude runs the actual shell commands — git diff, git grep, git branch — and reports what it finds. You don't fill out a form.

Pre-commit hook runs without Claude. BEFORE mode installs hooks/pre-commit into .git/hooks/pre-commit. From then on, 70 mechanical checks run on every git commit whether or not you remember to invoke the skill. Branch check, credential scan, Danger Zone audit, suppression patterns, security sinks, private key files, env var drift, migration rollback, server-side injection (SSRF, path traversal, NoSQL, prototype pollution), authz mistakes, crypto pitfalls, migration revision conflicts, weak-default secrets, developer contracts — all in pure shell.

CI integration closes the bypass gap. The hook can be skipped with git commit --no-verify. The GitHub Actions workflow cannot. BEFORE mode also installs ci/vibe-safe-ci.sh + ci/workflow.yml — the same checks run on every push and PR, with GitHub annotations for each finding. --no-verify is auto-escalated to ALARM if Claude proposes it.

CI writes a PR comment and step summary. When GH_TOKEN and PR_NUMBER are available, the CI script posts (or updates) a <!-- vibe-safe-audit --> comment on the PR with all findings — no need to dig through the Actions log. The comment is deduplicated: re-runs update the same comment in place. A matching job summary appears in the Actions tab. Fork PRs with read-only tokens get a logged skip, not a silent failure.

require_reviewer enforced in CI. Set require_reviewer: @alice in .vibesafe and the CI script checks GitHub's reviewer API — if the named reviewer hasn't been added, the check fails. Only runs when GH_TOKEN and PR_NUMBER are available; skips with a warning otherwise.

Optional tooling integration. When gitleaks, semgrep, or npm audit are installed in CI, vibe-safe runs them automatically. gitleaks detects high-entropy secrets that grep misses (Base64-encoded keys, rotated patterns). semgrep applies OWASP rule sets for injection, path traversal, and deserialization. npm audit flags known CVEs in your dependency tree. All three degrade gracefully — if a tool isn't installed, its check is silently skipped.

Agentic remediation. COMMIT mode fixes what's fixable instead of just flagging:

Developer-defined contracts. The developer sets the rules once in .vibesafe. vibe-safe enforces them for every PM contribution — no code review nagging required.

# .vibesafe
danger_zone: src/payments/
safe_zone: src/components/marketing/

require_tests: true          # New source files must have test changes
max_changed_files: 15        # Warn + SCOPE audit if exceeded
require_migration_rollback: true  # All migrations need a down/rollback
block_pattern: TODO          # Hard stop if TODO appears in implementation
require_reviewer: @alice     # Added to every PR description

Commit .vibesafe once. Every contributor — and the pre-commit hook and CI — gets the same rules automatically.

Modes

BEFORE

Runs before Claude writes anything. Checks your branch (creates a feature branch if on main), traces who owns the target files via git log, installs the pre-commit hook and CI workflow if missing, and produces a scoped prompt that limits what files Claude is allowed to touch.

If no .vibesafe exists: Claude scans the repo to discover rules (test file count, average commit size, migration rollback patterns, top committers), then generates a single document to paste into Slack or email — discovered rules with inline confirmation prompts, open questions below. PM sends it, pastes the answers back, Claude writes .vibesafe.

REVIEW

After Claude writes code, before you commit. Runs git diff HEAD for unstaged changes and git grep across all tracked files for credential patterns. Credentials live in files you didn't intend to change and won't appear in your diff.

SCOPE

When you think Claude changed more than you asked — or when max_changed_files fires. Claude asks what the original task was, then evaluates every changed file: IN SCOPE / LIKELY NEEDED / SUSPICIOUS / OUT OF SCOPE. Removes out-of-scope files with your confirmation.

COMMIT

70 checks across credentials, Danger Zones, code health, security patterns, server-side injection, authz/authn, crypto, scope, env vars, migrations, and developer contracts — each with remediation. When all pass: Claude generates the commit message and runs git commit for you.

PR

Reads git diff main...HEAD, asks why you're making the change, generates a complete PR description with what changed, what to test, flagged uncertainties, and suggested reviewers. Appends a PR safety artifact — a table showing what vibe-safe verified — so the reviewer sees the evidence without asking.

CONFLICT

Reads conflict markers and explains both sides in plain English — what the current version does, what your change does, what's specifically lost if you accept either side. Never recommends "accept all theirs/ours." Danger Zone file in conflict → STOP — CALL A DEVELOPER.

ALARM

When Claude proposes something that feels big. Assesses reversibility, shared-infra impact, and whether a developer would expect to review this. Auto-escalates for: git push --force, git commit --no-verify, direct database commands, CI check bypasses. Output: GO AHEAD / PAUSE AND CHECK / STOP — CALL A DEVELOPER.

VERIFY

Post-session clean check. Runs branch check, full file list for the PR, credential sweep, and commit message audit. Output: CLEAN or remaining flags with file:line evidence.

HISTORY

Scans recent git history for past mistakes needing active remediation. Finds commits that added credential patterns (even if later "deleted"), suspicious commit messages hinting at cleanup attempts, and recently deleted files. Distinguishes active exposure (still in HEAD) from historical exposure (removed but still in history — key rotation + git filter-repo required). Includes exact remediation steps.

EXPLAIN

Deep plain-English explanation of any vibe-safe flag. vibe-safe explain ssl tells you what SSL verification is, why disabling it is dangerous, what it looks like when it goes wrong, what Claude should have done instead, and one sentence you can say to your developer. For when "flagged" isn't enough and you want to actually understand it.

REVIEWER

For developers reviewing a PR opened by a non-technical contributor. Reads the full diff and produces: what the PM intended, what actually changed, which vibe-safe patterns are present, what to specifically test, and questions to ask if intent and implementation don't match.

Danger Zones

Files that need developer involvement regardless of change size:

Evidence

Built with TDD: baseline test first (RED) → skill written (GREEN) → loopholes closed (REFACTOR).

Baseline (no skill): Subagent playing a non-technical PM, test repo with a credential outside the diff, nginx.conf, an irreversible migration, and a scope creep file. Result: 0/4 caught. Committed directly to main with a vague message.

With skill: Same scenario. Result: 4/4 caught — credential flagged with file:line, main-branch commit stopped, migration and nginx.conf escalated to developer.

Five additional mode tests passed: BEFORE (main-branch stop), CONFLICT (auth file Danger Zone), COMMIT (real-incident quality gate weakening from PM's own experience).

v1.7 new-check baseline (20 tests, automated): Pre-commit hook tested against all three new v1.7 check categories in isolated git repos:

20/20 tests passed. .env.example template files excluded from Danger Zone (they're meant to be committed). Block pattern exemption verified per-file, not per-content-line.

v1.8.1 CI script tests (15 tests, automated): CI script tested with bare-repo-as-origin harness (enables git fetch/git diff origin/main...HEAD without network):

15/15 tests passed. Two bugs fixed during CI test authoring: env drift upgraded from warn to fail (parity with hook), block_pattern false positive when .vibesafe itself contains the blocked pattern.

v1.9.0 new-check verification (10 tests, automated): Five new manual checks and optional tooling integration tested:

10/10 tests passed. Optional tooling (gitleaks, semgrep, npm audit) fails gracefully when not installed — same checks still run via grep.

v1.10.0 expansion verification (25/25 hook, 20/20 CI, automated): Coverage threshold detection, developer contracts, false positive tuning, and GitLab/Bitbucket CI support tested across both scripts. All pre-existing checks preserved. Hook test count grew from 20→25; CI test count grew from 15→20.

v1.10.4 new security checks (29/29 hook, 24/24 CI, automated): Four new checks added and verified:

29/29 hook tests passed, 24/24 CI tests passed. auth.ts basename detection confirmed: files in auth/security namespace still hit Danger Zone before check 32; logger.info (backend logging pattern) correctly reaches check 32 and soft-flags without blocking.

v1.10.6–v1.10.8 credential-scan hardening (incident-driven): A real production incident — a DemoCard component with hardcoded email/password demo accounts bundled into the public JS artifact — exposed three compounding misses in the credential regex. All three fixed and regression-tested:

Nested test-dir exclusion also fixed: :!tests/ (root-only) → :(exclude,glob)**/tests/** so backend/tests/, app/tests/ are properly excluded from the cross-scan. 9/9 gap-regression tests passed.

v1.11.0 — 23 new checks across 6 tiers (41 tests, automated): Expanded the hook from 35 → 58 checks after a deep gap analysis of "what patterns vibes-coding produces that grep can catch":

• Tier 1 — credential shapes: connection strings with embedded creds, PEM key literals, JWT literals, public-bundled secret-named env vars (NEXT_PUBLIC_*/VITE_*), extended cloud-key prefixes (ASIA/ghs_/github_pat_/hf_/npm_/xox*/SG./whsec_)
• Tier 2 — authz/authn: permission decisions from client input, admin routes without auth middleware, webhooks without signature verification, JWT none algorithm, JWT without expiry/algorithms whitelist
• Tier 3 — data exposure: stack traces in HTTP responses, auth tokens in localStorage
• Tier 4 — server-side injection: SSRF, path traversal, open redirect, prototype pollution, NoSQL injection
• Tier 5 — destructive ops & CI: UPDATE/DELETE without WHERE, install-time package.json scripts, pull_request_target without SHA pinning, continue-on-error masking
• Tier 6 — crypto: weak hash (MD5/SHA1) in credential context, AES ECB mode

41/41 tests passed.

v1.11.1 — migration revision conflict (check 58, 4 tests): After a parallel-migration incident (two 019_* migrations both pointing to 018_client_deliverables, breaking alembic upgrade head), added detection: when a migration is staged, its down_revision is compared against every committed migration — a shared parent (split chain) is blocked with both filenames and the correct head to chain from. 4/4 tests passed.

v1.12.0 — Python pitfalls + supply chain (checks 59–64, 14 tests):

• unsafe YAML loading (RCE), native binary deserialization (RCE), bare except:, dynamic code-execution calls in source, random module in security-named Python files
• Azure AccountKey= and GCP private_key_id added to CRED_PATTERN
• Unpinned GitHub Actions (@v*/@main/@latest) — warns before the danger-zone bail so it's always visible

14/14 tests passed.

v1.13.0 — weak defaults & misconfig (checks 65–68, 11 tests):

• Default/placeholder secret values (JWT_SECRET = "changeme", SIGNING_KEY = "your-secret-here") — catches the UPPER/camelCase/hyphenated secret names the case-sensitive check 2 misses
• Insecure cookie flags (httpOnly:false/secure:false in cookie context)
• World-writable permissions (chmod 777 / os.chmod 0o777)
• Go math/rand in security-named files — completes the crypto-RNG trio (JS check 26 → Python 63 → Go 68)

11/11 tests passed. Hook now runs 70 mechanical checks.

What vibe-safe can't catch — and how to handle it

Three categories of risk that grep cannot cover.

API response data exposure

Why not catchable: Whether a response leaks sensitive fields depends on what the serializer includes — that requires understanding the data model, not reading diffs.

How to handle:

• Use allowlist serializers, not raw model returns. return await db.user.findFirst(...) directly in a route handler is the root cause. Fix with a schema that explicitly names exposed fields: response_model=UserPublic (FastAPI), fields = ['id', 'name'] (DRF), as_json(only: [:id, :name]) (Rails), select: { id: true } (Prisma).
• Runtime scan on staging. OWASP ZAP (free) or Burp Suite. Check that password_hash, stripe_customer_id, ssn, internal_id don't appear in responses before launch.
• Add a response shape test. Assert which fields appear and fail if new ones are added without review.

Privacy policy

Why not catchable: Whether you need one depends on what data you collect, where your users are, and applicable law — none of which are in the code.

How to handle:

• The trigger is collecting personal data, not shipping code. email, name, phone, ip_address, location, device_id, date_of_birth, behavioral tracking — any of these mean you need a policy before real users.
• Jurisdiction: GDPR for EU/EEA users, CCPA for California users (>$25M revenue, >50k users, or >50% revenue from selling data), UK GDPR post-Brexit.
• Fast path: iubenda, Termly, or GetTerms.io — ~$10/month, compliant output. Don't write your own or copy from another site.
• Developer action before adding any PII field: document purpose, retention period, and who has access.

Data storage architecture

Why not catchable: Where data ends up, who can access it, and whether it's encrypted requires understanding infrastructure — not reading diffs.

How to handle:

• Four questions before building any new data entity: Where is it stored? Who can read it? How long is it kept? Is it encrypted at rest? If you can't answer these, the feature isn't ready to build.
• Logs are a data store. Whatever goes into console.log, logger.info, or your observability platform (Datadog, Sentry, CloudWatch) is stored, queryable, retained for months. Treat log destinations with the same access controls as your database.
• Third-party SDKs are data stores. Segment, Mixpanel, Intercom, Sentry, FullStory — adding any of these sends user data to their infrastructure. Check what each collects by default, whether PII can be excluded, and whether their DPA covers your jurisdiction.
• Gate question before any new integration: "Does this send user data off our infrastructure? What data, to whom, under what terms?" Answer this before the SDK lands in package.json.

Why "not in my diff" is the most dangerous rationalization

Credentials live in files you didn't intend to change. If you scan only staged files, you miss them. vibe-safe runs git grep across all tracked files in every REVIEW and COMMIT check — the same command that catches a secret committed three weeks ago in a different session.

License

MIT