Skip to content

How it works

  1. A PR is opened or updated. Your workflow runs git diff base...head — three dots, so the diff is the PR's own changes measured from the merge base, not a two-dot comparison that would also include the reverse of anything landed on the base branch since — and POSTs it to your vibecheck instance.
  2. vibecheck generates a session, stores the diff, reads it once to form a blind interpretation, writes the questions (the high-level one plus a scoped question per part of the change, each anchored to its lines), and returns a URL with a one-time token — https://your-vibecheck/s/<token>.
  3. The PR author opens the link and walks it one screen at a time: each screen shows the slice of the diff a question is about and a box to answer it. No login required — the token in the URL is the credential.
  4. Each answer is graded on submit by Claude against the stored interpretation, and the result (pass/fail plus a note) is shown before the next screen. Marking is lenient — contradicting the diff fails a question; a terse or high-level-but-correct answer passes it. A wrong answer can be retried up to MAX_QUESTION_ATTEMPTS times, after which vibecheck reveals the answer and moves on (that question then counts for nothing, neither toward nor against the pass). A per-screen "Skip" button fails the question instantly, reveals the answer and moves on, the same as running out of tries. A per-screen "Explain it for me" button gives a plain-language walkthrough of that section, free and with no effect on the mark. The session passes once PASSINGMARKS screens are correct, and fails as soon as reaching that many is no longer possible.
  5. vibecheck reports the verdict on the PR as a vibecheck/verdict commit status: pending until the walkthrough is decided, then green or red. The workflow job that opens the session, grill, never blocks: it passes even if vibecheck is down. Whether the verdict blocks merging is your call: require vibecheck/verdict in branch protection to make it a gate, or leave it unrequired and it's advisory. Nothing sits on a runner waiting for a human.

With ALLOW_RESTART=true, a session that ends red can be restarted from its result page with Start over: same commit, same link, a fresh sheet of questions, and the vibecheck/verdict status goes back to pending. See Blocking PRs.