npm package: @safetnsr/vibe-check
Description: lint the vibes before you push — AI agent session auditor for git diffs
Author: safetnsr
Latest version: 1.5.1
Deprecated: use @safetnsr/vet instead — npx @safetnsr/vet

# vibe-check

> ⚠️ **DEPRECATED** — use [@safetnsr/vet](https://github.com/safetnsr/vet) instead. vet includes everything vibe-check did plus 5 more checks, `--fix`, `--watch`, and CI mode. `npx @safetnsr/vet`

---

> lint the vibes before you push

AI agent session auditor that scans git diffs for anti-patterns before you push. catches stubbed tests, deleted error handlers, hardcoded secrets, empty catch blocks, and other signs of vibe coding gone wrong.

designed to be called by agents, not just humans. run `vibe-check --json` in your agent workflow and consume the structured output to fix issues before pushing.

## install

```bash
# zero install — just run it
npx @safetnsr/vibe-check

# or install globally
npm install -g @safetnsr/vibe-check
```

## usage

run in any git repo with uncommitted or staged changes:

```bash
npx @safetnsr/vibe-check
```

example output:

```
🔍 vibe-check
────────────────────────────────────────

🔑 hardcoded secret (1)
  src/config.ts:12  const api_key = "sk-****"

🛡️  error handler removed (1)
  src/server.ts:45  } catch (err) {

🕳️  empty catch block (1)
  src/api.ts:23  catch (e) {}

🧪 test stub (2)
  tests/app.test.ts:10  expect(true).toBe(true);
  tests/app.test.ts:15  it('handles edge case', () => {})

📝 TODO/FIXME in prod (1)
  src/utils.ts:8  // TODO: fix this later

────────────────────────────────────────
scanned 8 files, 312 lines
risk score: 73/100
✗ threshold 50 exceeded — fix before pushing
```

## flags

| flag | description |
|------|-------------|
| `--explain` | show why each finding is an agent anti-pattern |
| `--since <sha>` | scan from `<sha>` to HEAD (entire agent session) |
| `--report` | generate `VIBE_CHECK.md` audit report |
| `--json` | machine-readable output |
| `--threshold <n>` | risk score threshold (default: 50) |
| `--hook` | install as git pre-push hook |
| `--ci` | CI mode — no color, GitHub Actions annotations |
| `--debug` | show git commands, diff size, parse time |
| `--version`, `-v` | show version |
| `--help`, `-h` | show help |

## what it detects

| pattern | score | description |
|---------|-------|-------------|
| hardcoded secret | 30 | `api_key = "..."`, `password = "..."`, etc. (ignores `process.env`, skips test files) |
| empty catch block | 25 | `catch (e) {}` — silently swallows errors |
| deleted error handler | 20 | removed `try/catch`, `.catch(`, `except:` (skipped if alternative error handling added) |
| test stub | 15 | `expect(true).toBe(true)`, empty test bodies |
| TODO/FIXME in prod | 10 | `// TODO` or `// FIXME` in non-test files |
| large deletion | 5/50 lines | >50 lines deleted without test changes |

risk score is capped at 100. exit code 1 if score meets or exceeds threshold.

## --explain

```bash
npx @safetnsr/vibe-check --explain
```

adds a one-line explanation per finding type:

```
🛡️  error handler removed (1)
  src/server.ts:45  } catch (err) {
  ↳ why: agents remove error handling when refactoring because their test
         environment doesn't surface the failure — production will
```

## --since

scan an entire agent session across multiple commits:

```bash
npx @safetnsr/vibe-check --since HEAD~5   # last 5 commits
npx @safetnsr/vibe-check --since abc1234  # from specific sha
```

useful when you let an agent run for a while and made several commits before reviewing.

## --report

generate a markdown audit report:

```bash
npx @safetnsr/vibe-check --report
```

writes `VIBE_CHECK.md` to the repo root with timestamp, detected agent (claude-code / cursor / aider), risk score, verdict, and all findings with explanations. designed to be attached to pull requests.

`VIBE_CHECK.md` is automatically added to `.gitignore`.

## stats

view session history and pattern analytics:

```bash
npx @safetnsr/vibe-check stats
```

```
📊 vibe-check stats
────────────────────────────────────────
sessions scanned:    23
average risk score:  31.4
pass rate:           78%

top findings:
  deleted error handler   41%  ████████████████████
  test stub               28%  ██████████████
  hardcoded secret        18%  █████████
  todo in prod            13%  ██████

by agent:
  claude-code   18 sessions
  cursor         5 sessions

trend (last 7 sessions):
  ▂▅▃▇▂▁▄  (scores: 15 42 28 73 20 8 35)
────────────────────────────────────────
```

history is stored in `.vibe-check-history.json` at the repo root (auto-added to `.gitignore`).

## config file

create `.vibecheck.yml` to configure per-repo:

```yaml
threshold: 60

ignore:
  - "src/legacy/**"
  - "migrations/**"
  - "{seeds,fixtures}/**"

patterns:
  disable:
    - todo-in-prod

  custom:
    - type: "unsafe-any"
      pattern: ": any"
      files: "src/**/*.ts"
      message: "unsafe 'any' type — agent shortcut"
      score: 10
```

cli flags override config file values.

## json output

```bash
npx @safetnsr/vibe-check --json
```

```json
{
  "score": 73,
  "threshold": 50,
  "findings": [
    {
      "type": "hardcoded-secret",
      "file": "src/config.ts",
      "line": 12,
      "message": "hardcoded secret detected",
      "score": 30,
      "snippet": "const api_key = \"sk-****\""
    }
  ],
  "pass": false
}
```

## git hook

install as a pre-push hook:

```bash
npx @safetnsr/vibe-check --hook
```

blocks every push where the risk score exceeds the threshold. history is recorded automatically on every hook run.

## ci / github actions

```yaml
name: vibe-check
on: [push, pull_request]

jobs:
  vibe-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: npx @safetnsr/vibe-check --ci --threshold 50
```

`--ci` outputs GitHub Actions annotations that show up directly on pull requests.

## threshold

```bash
npx @safetnsr/vibe-check --threshold 1    # strict — flag everything
npx @safetnsr/vibe-check --threshold 80   # relaxed — only critical issues
npx @safetnsr/vibe-check --threshold 0    # report only, never block
```

## agent integration

vibe-check is designed to be consumed by AI coding agents (claude code, cursor, aider). run it as part of your pre-push workflow to self-audit before committing.

### claude code — add to CLAUDE.md

```markdown
## pre-push checklist
before pushing any changes, run:
```bash
npx @safetnsr/vibe-check --json
```
if `pass` is false, fix all items in `critical[]` using the `fix_line` when available, then re-run until clean.
```

### consume and fix loop (pseudocode)

```
result = exec("npx @safetnsr/vibe-check --json")
data = JSON.parse(result.stdout)

if not data.pass:
  for finding in data.critical:
    if finding.fix_line:
      # apply fix_line at finding.file:finding.line
      edit(finding.file, old=finding.snippet, new=finding.fix_line)
    else:
      # manual fix required — read finding.fix for guidance
      print(f"manual fix needed: {finding.fix}")
  
  re-run vibe-check until data.pass == true
```

### json schema

```json
{
  "pass": true,
  "score": 0,
  "threshold": 50,
  "summary": "no issues found",
  "critical": [],
  "warnings": [],
  "findings": [],
  "filesScanned": 12,
  "linesScanned": 847
}
```

finding shape:
```json
{
  "type": "hardcoded-secret",
  "file": "src/config.ts",
  "line": 12,
  "snippet": "const api_key = \"sk-****\"",
  "fix": "replace with process.env.API_KEY ?? ''",
  "fix_line": "const api_key = process.env.API_KEY ?? ''"
}
```

`fix_line` is `null` for findings where no single-line replacement is possible.

## the agent workflow toolkit

vibe-check pairs with [ai-ready](https://github.com/safetnsr/ai-ready) to bookend every agent coding session:

```bash
npx @safetnsr/ai-ready src/auth/   # before: know the risks
# ... run your agent session ...
npx @safetnsr/vibe-check           # after: catch what it broke
```

## why

vibe coding with AI agents is fast. too fast. agents stub tests to make CI green, delete error handlers to "simplify", add empty catch blocks to silence TypeScript errors, and leave hardcoded secrets in config files. vibe-check catches these patterns before they hit your remote.

## license

MIT