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, outdated dependencies, CI, unsafe web APIs, and overbroad desktop permissions.

View on GitHubInstall
~/project - itworksbut scan
ITWORKSBUT
$ itworksbut scan
[ok] env checks armed
[ok] dependency freshness checks armed
[scan] looking for "it works, but..." risks
[high] dependencies are outdated

Install

Two commands before the prototype escapes.

npm
npm install --global itworksbut
itworksbut scan
Homebrew
brew tap oliverjessner/tap
brew install itworksbut
itworksbut scan

Problem

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.

CRITICAL

Tracked .env

Finds env files that Git already knows about before keys become incident reports.

MEDIUM

Dependency drift

Flags missing lockfiles and outdated packages before stale dependencies become release debt.

HIGH

Weak CI

Detects CI that installs, skips tests, or never builds before shipping to main.

HIGH

Unsafe web APIs

Looks for missing auth, open CORS, raw SQL strings, and endpoints with no brakes.

HIGH

Overbroad desktop permissions

Checks Electron and Tauri settings that make local apps too powerful by default.

MEDIUM

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. Add --report when you want clean, machine-readable receipts for CI, code scanning, and automation.

findings.log
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, but your dependencies are outdated.Review stale direct dependencies and update them before the next release.
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.

01

Scan project

Run locally or in CI. ItWorksBut reads files and reports findings without modifying your repo.

02

Detect risk patterns

Checks JavaScript, Node.js, web, Tauri, Electron, Git, packages, dependency freshness, and CI.

03

Print findings

Severity-ranked output and optional reports show which risks block shipping.

04

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 with --report, 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 high

Output 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.

--report

One flag to keep a durable scan report alongside local terminal triage.

Last gate

Run it before your prototype becomes production.

A demo can look done while the repo is still leaking, trusting the browser, shipping stale dependencies, or leaving desktop permissions wide open.

View on GitHubCopy install commands