reality-check

A Definition-of-Done gate for Claude Code. It stops the agent (and you) from saying "done / works / live / deployed" until the change has actually been exercised against real data — and it physically blocks production deploys until that proof exists.

Compiling isn't proof. A green build isn't proof. A subagent saying "verified" isn't proof. Running the real path and pasting the real output is.

Built for and dogfooded on the vibe2prod channel — taking vibe-coded projects to production without the "it works on my machine" lie. → watch on YouTube

Why

Coding agents are confident. They'll tell you a feature is live when it's reading mock data, that tests pass when the test passes on broken code, that something is "wired up" when nothing ever ran. Then it hits production and it doesn't work.

reality-check makes "done" mean observed working, not intended to work.

What's in the box

File	Type	Job
commands/reality-check.md	slash command	Walks a 6-step proof checklist: claim → real-data grep → run it end-to-end → break-it test → list gaps → verdict. On pass, writes a 15-minute marker.
hooks/reality-check-gate.py	PreToolUse(Bash) hook	Blocks deploy.sh and git push main/master/prod unless a fresh marker exists. Consumes the marker (one-shot).
hooks/reality-check-stop.py	Stop hook	Advisory nudge: if the last turn claimed "done / live / working" with no pasted proof, reminds you to show evidence. Never blocks.

Both hooks fail open — any internal error just lets the command through, so they can never wedge a session.

Install

Everything lives under ~/.claude/.

# 1. command
mkdir -p ~/.claude/commands ~/.claude/hooks
cp commands/reality-check.md ~/.claude/commands/
cp hooks/reality-check-gate.py hooks/reality-check-stop.py ~/.claude/hooks/
chmod +x ~/.claude/hooks/reality-check-*.py

Then wire the hooks in ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "python3 ~/.claude/hooks/reality-check-gate.py" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "python3 ~/.claude/hooks/reality-check-stop.py" }
        ]
      }
    ]
  }
}

Restart Claude Code (or reload settings) and you're gated.

Usage

Run it against whatever you're about to claim works or ship:

/reality-check the pricing page pulls live Stripe data

The agent must paste real evidence for each step. If it genuinely passes, it unlocks the deploy gate for 15 minutes (one deploy). If it doesn't, it says NOT VERIFIED and the gate stays shut.

Try to deploy without passing and the gate blocks it:

REALITY-CHECK GATE blocked a deploy/publish command.
Prove it works with REAL data before shipping:
  1. Run /reality-check for what you are shipping.
  ...

Tuning

• What counts as a deploy — edit the _EXEC_DEPLOY / _GIT_PUSH_PROD regexes in reality-check-gate.py to match how your projects ship. Defaults cover deploy.sh and pushes to prod branches.
• Marker lifetime — MAX_AGE (default 900s / 15 min).
• What trips the advisory nudge — the STRONG / PROOF word lists in reality-check-stop.py.

License

MIT — use it, fork it, ship it, do whatever. No strings.