vibe-check is a tiny CLI that turns a folder of candidates into a browser review session.
People vote — the ranked result lands back in the terminal.
That’s the vibe. ♥ Thanks!
3 of 3 reviewed — the summary is printing in the terminal.
Agents can generate plenty of options. vibe-check helps them validate the alternatives with human feedback, saving time and effort for everyone. The result returns as a ranked summary.
Drop two or more self-contained .html or .md files in one directory. Each file
is a Vibe — one immutable creative candidate. No build step, no uploads, no accounts.
One local URL, one candidate at a time. Voters give a Verdict — pass, keep, love — rate stars, or leave a comment. Anything can be skipped or revisited before the session ends.
Stop with Ctrl+C and the Campaign Result prints where you started: Loves then Keeps, average
star rating, or submitted comments — ready for an agent to act on.
Run the CLI against a folder with at least two candidates. Open the local URL it prints, or use
--tunnel to share the review remotely.
Each voter session reviews one Vibe at a time in the browser. Feedback is revisable until the session ends — no sign-up, no ceremony.
Press Ctrl+C to end the session and print the result. Pipe it, save it, or review it—--json
and --output keep the signal moving.
The creator chooses one voting system when opening a Campaign.
Every system allows unanswered candidates, and voters can revise earlier feedback before the session ends.
defaultFast triage: Pass, Keep, or Love. A Love counts as a Keep with extra emphasis. The summary sorts by Loves, then Keeps.
One-to-five stars per Vibe for relative ranking when options are close. The summary ranks by average rating, then rating count.
Optional written feedback per Vibe — continue without writing anything. The summary reports comment counts and lists what people said. No ranking, just signal.
The whole product is one npm package. The installed command is vibe-check — the scope just names the publisher.
$ npm install -g @we-are-singular/vibe-check
Teach your coding agent when and how to run a vibe check. Install with the Skills CLI, or print the built-in guide with vibe-check skill.
$ npx skills add we-are-singular/vibe-check
| Flag | Alias | What it does |
|---|---|---|
--voting tinder|stars|comment |
--vote |
Choose the feedback mechanic. Default: tinder. |
--name "Which hero wins?" |
-n |
Title the Campaign — a name or the review question itself. |
--port 4214 |
-p |
Use another loopback port when 4173 is taken. |
--tunnel cloudflare|ngrok |
-t |
Share a temporary public link through an installed tunnel provider. |
--json |
— | Emit newline-delimited JSON lifecycle events for automation. |
--output results.jsonl |
-o |
Mirror every event — feedback and the final summary — to a file. |
Full usage, campaign-file rules, and event formats live in the README. The domain language (Vibes, Campaigns, Verdicts) is defined in CONTEXT.md.
vibe-check is early and opinionated — help shape it. File issues, propose voting systems, or just tell us what you vibe-checked.