npm
npm install --global itworksbut
itworksbut scan
ItWorksButGitHub
Node.js CI scanner for vibe-coded projects
ItWorksBut
Finds the hidden risks in vibe-coded projects.
Your prototype boots. The demo clicks. The deploy is green. ItWorksBut checks the parts AI-built apps usually skip: secrets, lockfiles, CI, unsafe web APIs, and overbroad desktop permissions.
ITWORKSBUT
$ itworksbut scan
[ok] env checks armed
[scan] looking for "it works, but..." risks
[critical] .env appears to be tracked
Install
Two commands before the prototype escapes.
Homebrew
brew tap oliverjessner/tap
brew install itworksbut
itworksbut scanProblem
A working app can still be a loaded deployment.
Vibe coding gets you to the first demo fast. Production asks different questions: what got committed, who can call the API, what CI actually checks, and what permissions your desktop app quietly opened.
Tracked .env
Finds env files that Git already knows about before keys become incident reports.
Missing lockfile
Flags dependency trees that only reproduce on the machine where the prototype was born.
Weak CI
Detects CI that installs, skips tests, or never builds before shipping to main.
Unsafe web APIs
Looks for missing auth, open CORS, raw SQL strings, and endpoints with no brakes.
Overbroad desktop permissions
Checks Electron and Tauri settings that make local apps too powerful by default.
Missing rate limits
Warns when login, AI, upload, or API routes have no visible throttle layer.
Example output
Terminal drama, useful receipts.
The console output is loud on purpose. Machine-readable reporters stay clean for CI, code scanning, and automation.
CRITICALIt works, but your .env is tracked.Fix prompt generated for env.env-file-tracked
HIGHIt works, but your Tauri permissions look too generous.Inspect allowlist, shell, fs, and remote URL capabilities.
MEDIUMIt works on your machine, but your dependency tree is not locked.Add the correct package manager lockfile and use reproducible installs.
INFOCopy-ready fix prompt generated.Paste it into your coding agent and fix the finding without leaking secrets.
How it works
Static checks with agent-ready next steps.
Scan project
Run locally or in CI. ItWorksBut reads files and reports findings without modifying your repo.
Detect risk patterns
Checks JavaScript, Node.js, web, Tauri, Electron, Git, package, and CI configuration.
Print findings
Severity-ranked output tells you which risks block shipping and which need cleanup.
Generate fix prompts
Every finding includes a practical prompt for coding agents with clear boundaries.
Agent prompt angle
It does not just complain. It briefs the agent.
Findings include copy-ready remediation prompts: what to inspect, what to change, what tests to add, and what never to print. That makes ItWorksBut a security scanner and a repair brief in one pass.
COPY-READY FIX PROMPT
You are a senior security engineer working in this repository. Fix the ItWorksBut finding
database.raw-sql-interpolation. Treat model and user input as untrusted. Keep
behavior intact, add focused tests, and do not silence the check unless the risk is actually
fixed.
CI
Make the build fail before production does.
Run ItWorksBut on pull requests, push SARIF into GitHub Code Scanning, or keep JSON output for your own automation.
.github/workflows/itworksbut.yml
name: ItWorksBut
on:
pull_request:
push:
branches: [main]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npx itworksbut scan --fail-on highOutput formats
Readable by humans. Parseable by machines.
Console
Neon severity output for local scans and fast triage.
JSON
Structured findings for scripts, dashboards, and agent workflows.
SARIF
GitHub Code Scanning-friendly output for CI visibility.
Last gate
Run it before your prototype becomes production.
A demo can look done while the repo is still leaking, trusting the browser, or shipping desktop permissions with the doors open.