{
  "markdown": "# npx-vibe\n\n[![npm version](https://img.shields.io/npm/v/npx-vibe.svg?color=22d3ee)](https://www.npmjs.com/package/npx-vibe)\n[![npm weekly downloads](https://img.shields.io/npm/dw/npx-vibe.svg?color=34d399)](https://www.npmjs.com/package/npx-vibe)\n[![npm total downloads](https://img.shields.io/npm/dt/npx-vibe.svg?color=a78bfa)](https://www.npmjs.com/package/npx-vibe)\n[![CI](https://github.com/Devrajsinh-Jhala/NPM-Vibe-check/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Devrajsinh-Jhala/NPM-Vibe-check/actions/workflows/ci.yml)\n[![Node.js](https://img.shields.io/node/v/npx-vibe.svg)](https://www.npmjs.com/package/npx-vibe)\n[![License: MIT](https://img.shields.io/npm/l/npx-vibe.svg)](./LICENSE)\n\n**Evidence-first safety checks for npm packages and project dependencies before developers, coding agents, or MCP clients execute them.**\n\n`npx-vibe` resolves packages from the public npm registry, downloads and verifies their tarballs without executing them, inspects install-time code, and prints clear **Proceed**, **Caution**, or **Block** verdicts. Use it for one-off `npx` commands or scan an existing project's direct dependencies.\n\nThe default scan is deterministic, local, and requires no account or API key. AI review is optional, opt-in, and lets you choose an exact model or a maintained `fast`, `balanced`, or `strong` profile. Version 1.5 also ships a zero-dependency MCP server with read-only package, project, and model-catalog tools.\n\n- [npm package](https://www.npmjs.com/package/npx-vibe)\n- [Official MCP Registry entry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Devrajsinh-Jhala%2Fnpx-vibe)\n- [Live website](https://devrajsinh-jhala.github.io/NPM-Vibe-check/)\n- [GitHub repository](https://github.com/Devrajsinh-Jhala/NPM-Vibe-check)\n- [Security policy](./SECURITY.md)\n- [Changelog](./CHANGELOG.md)\n- [Release process](./RELEASING.md)\n\n## Live adoption\n\nThe [project website](https://devrajsinh-jhala.github.io/NPM-Vibe-check/) displays the current seven-day download total directly from npm's public download API:\n\n- [weekly total](https://api.npmjs.org/downloads/point/last-week/npx-vibe)\n- [daily seven-day range](https://api.npmjs.org/downloads/range/last-week/npx-vibe)\n\nThe counter is live rather than hard-coded, and the site links to the source data. npm download counts measure package fetches, not unique users. They are momentum signals—not proof of package safety or quality—but they show that the package is being discovered and installed.\n\n## Quick start\n\nReview a package without executing it:\n\n```bash\nnpx npx-vibe esbuild\n```\n\nUse it as a guarded replacement for `npx`:\n\n```bash\nnpx npx-vibe cowsay -- hello from npx-vibe\n```\n\nOr install the command globally:\n\n```bash\nnpm install -g npx-vibe\nnpx-vibe <package>\n```\n\nScan an existing project's direct dependencies:\n\n```bash\nnpx npx-vibe --project .\n```\n\nGive a coding agent a stable, read-only result:\n\n```bash\nnpx --yes npx-vibe@latest --agent esbuild\nnpx --yes npx-vibe@latest --agent --project .\n```\n\nOr connect the native MCP server:\n\n```bash\nnpx --yes npx-vibe@latest --mcp\n```\n\n## Use npx-vibe with coding agents\n\n`--agent` turns the scanner into a predictable machine interface. It implies check-only mode, writes only JSON to stdout, disables terminal color and local review-memory writes, and never executes package code. Operational failures are JSON too, so an agent can fail closed instead of interpreting partial terminal output.\n\nInstall the portable Agent Skill for Codex, Claude Code, Cursor, VS Code, and other compatible agents:\n\n```bash\nnpx skills add Devrajsinh-Jhala/NPM-Vibe-check --skill npx-vibe -g\n```\n\nThe skill tells an agent to preflight unfamiliar packages before `npx`, `npm exec`, or dependency installation and then apply the normalized decision:\n\n| `decision.action` | Required behavior |\n| --- | --- |\n| `continue` | Continue only with the package action the user already requested |\n| `review` | Pause, summarize source evidence, and request human approval |\n| `stop` | Do not install or execute the package |\n| `retry` | The scan is incomplete; report the error and do not infer safety |\n\nExample envelope:\n\n```json\n{\n  \"schemaVersion\": 2,\n  \"tool\": { \"name\": \"npx-vibe\", \"version\": \"2.0.0\" },\n  \"kind\": \"package-scan\",\n  \"status\": \"complete\",\n  \"decision\": {\n    \"verdict\": \"caution\",\n    \"riskScore\": 43,\n    \"action\": \"review\",\n    \"exitCode\": 2,\n    \"mayContinue\": false,\n    \"safeToExecute\": false,\n    \"requiresApproval\": true,\n    \"requiresHumanReview\": true,\n    \"blocked\": false,\n    \"mustStop\": false\n  },\n  \"subject\": {\n    \"type\": \"package\",\n    \"name\": \"esbuild\",\n    \"requested\": \"latest\",\n    \"version\": \"0.28.1\"\n  },\n  \"report\": {}\n}\n```\n\nThe complete deterministic report remains under `report`. Require `schemaVersion === 2`, `status === \"complete\"`, and `decision.mayContinue === true` before continuing automatically. The outer `npx --yes` only suppresses npm's download prompt; agent mode rejects npx-vibe's execution flags such as `--force` and `--yes`.\n\nAI remains off by default in agent mode. If a user explicitly requests model interpretation, use a provider-specific environment variable and add `--ai online --provider <provider>`; never place a key in a generated command.\n\n## Connect npx-vibe through MCP\n\nVersion 1.5 includes a read-only [Model Context Protocol](https://modelcontextprotocol.io/) server over stdio. It gives MCP-compatible AI applications a native tool surface without teaching them to parse terminal text or construct shell commands.\n\nAdd this server configuration to an MCP client that supports local stdio servers:\n\n```json\n{\n  \"mcpServers\": {\n    \"npx-vibe\": {\n      \"command\": \"npx\",\n      \"args\": [\"--yes\", \"npx-vibe@latest\", \"--mcp\"]\n    }\n  }\n}\n```\n\nGlobal installations can use `npx-vibe-mcp` as the command with no arguments. Run `npx npx-vibe --mcp --help` for server-specific help.\n\nThe server exposes four schema-backed tools:\n\n| MCP tool | Purpose |\n| --- | --- |\n| `scan_package` | Resolve, verify, and inspect one public npm package without executing it |\n| `scan_project` | Review the dependency tree from a project manifest and lockfile |\n| `approve_scripts` | Decide which dependencies may run install scripts under npm 12 |\n| `list_providers` | Return supported AI providers and where each publishes its model list |\n\nScan results return the same versioned decision contract in both `structuredContent` and a JSON text block for client compatibility. The tools are annotated read-only and non-destructive. `review` still requires human approval, while `stop`, `retry`, and MCP tool errors fail closed.\n\nAI remains off unless a tool call explicitly selects it. API keys are intentionally excluded from MCP tool arguments: configure provider-specific environment variables on the MCP server process so credentials do not enter prompts or tool history.\n\n`npx-vibe@2.0.0` is [active in the official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Devrajsinh-Jhala%2Fnpx-vibe) as `io.github.Devrajsinh-Jhala/npx-vibe`. Registry clients can resolve the verified npm package and start its local stdio server with `--mcp`.\n\n## Why developers use it\n\nRunning `npx some-package` can download code and execute a package binary immediately. Packages may also declare lifecycle scripts that run during installation.\n\n`npx-vibe` inserts a visible checkpoint before execution:\n\n1. Resolve the exact npm package version.\n2. Fetch registry, download, maintainer, publisher, and repository context.\n3. Download the tarball without running package code.\n4. Verify npm integrity metadata and inspect bounded source files.\n5. Show matched evidence and a risk verdict.\n6. Execute only after the verdict allows it.\n\nFor an existing app, `--project` repeats the same read-only review across direct registry dependencies and aggregates the result. This makes the check useful in local development and pull-request CI, not only before an unfamiliar `npx` command.\n\nBy default, execution uses npm with install scripts ignored. Use `--allow-install-scripts` only when you intentionally want reviewed root lifecycle scripts to run.\n\n## Evidence, not mystery scores\n\nEvery deterministic source finding includes the matched line and a bounded excerpt. Registry popularity is displayed separately as context and never overrides suspicious code. Local review memory is keyed by the verified package integrity—not merely its name or version. The example below mirrors a real scan; registry dates and download counts naturally change over time.\n\n```text\n$ npx npx-vibe esbuild\n! npx-vibe: Caution  risk 43/100\nesbuild@0.28.1\n\nDownloads: 241,858,907/week  Package age: 3132d  Version age: 12d\nInstall hooks: postinstall\nEstablished signals: long registry history, high weekly adoption, linked GitHub repository\nRegistry popularity and age provide context, but never override code findings.\nReview memory: unchanged tarball since 2026-06-25; previous Caution 43/100.\nAI review: skipped (Heuristic-only mode; AI was not requested.)\n\nFindings:\n- MEDIUM   lifecycle_hook in package.json\n  postinstall runs: node install.js\n  Evidence: postinstall: node install.js\n- MEDIUM   network_and_shell in install.js\n  Code combines network access with shell execution.\n  Evidence line 147: fetch(url) ... child_process.execSync(...)\n\nAction: review recommended before execution.\n```\n\nA popular package can still receive **Caution** when it performs sensitive install-time behavior. That is intentional: maturity is useful context, not a security exemption.\n\nWhen AI is explicitly enabled, the resolved provider and model are visible in the result. This example is adapted from the successful Gemini 3.5 Flash run on June 25, 2026; model wording can vary:\n\n```text\n$ npx npx-vibe --ai online --provider gemini --model gemini-3.5-flash esbuild\n! npx-vibe: Caution  risk 43/100\nesbuild@0.28.1\n\nInstall hooks: postinstall\nAI review: Gemini gemini-3.5-flash (high confidence)\nAI evidence: 0 source-backed findings\n\nAI interpretation: The selected install script appears to resolve a platform-specific binary.\nNo additional source-backed credential access, obfuscation, or persistence finding was\nidentified, but the deterministic install-time network and process evidence remains.\n\nAction: review recommended before execution.\n```\n\n## What it checks\n\n| Area | Signals |\n| --- | --- |\n| Known vulnerabilities | OSV.dev advisories for the exact resolved version, with CVE aliases and severity. No API key; batched across a whole tree |\n| Registry context | package age, version age, weekly downloads, maintainers, publisher, license, deprecation. Reported, never scored |\n| Install behavior | `preinstall`, `install`, `postinstall`, and their script targets. `prepare`, `prepublish`, `preprepare`, and `postprepare` are reported separately as context, because npm does not run them when a published tarball is installed |\n| Tarball safety | npm integrity verification, unsafe paths, escaping symlinks, archive size and entry limits |\n| Source behavior | secret/environment access, network calls, shell execution, external payloads, obfuscation, persistence, mining indicators |\n| Dependency metadata | remote Git/HTTP/file protocols in the fields npm actually installs, and lockfile install-script indicators |\n| Repository context | GitHub repository, stars, last update, last push, and latest commit |\n| Review memory | verified integrity match, previous verdict, selected-file changes, lifecycle-hook changes, and finding deltas |\n| Optional AI | local Ollama or supported online providers, used only after explicit opt-in and a heuristic trigger |\n\n## Built for repeated use\n\n`npx-vibe` always performs a fresh registry lookup, tarball download, integrity verification, and deterministic scan. Local review memory adds comparison context after those checks:\n\n```text\nReview memory: unchanged tarball since 2026-06-25; previous Caution 43/100.\n```\n\nWhen the integrity changes:\n\n```text\nVersion comparison: 0.28.1 → current; integrity changed.\n2 selected files changed; findings +1/-0; install hooks unchanged.\n```\n\nThe history file stores package versions, integrity hashes, selected-file hashes, finding identifiers, verdicts, and model metadata. It does not store package source, API keys, environment values, or local project files. The default location is `~/.npx-vibe/reviews.json`.\n\n## Verdicts\n\n| Verdict | Meaning | Check-mode exit code |\n| --- | --- | --- |\n| **Proceed** | No meaningful deterministic risk signal was found | `0` |\n| **Caution** | Reviewable behavior or incomplete context requires human judgment | `2` |\n| **Block** | Critical behavior or a high-risk review result was detected | `3` |\n| Operational error | Registry, network, input, or internal failure | `1` |\n\nRegistry context — package age, version age, and download volume — is reported at the `info` severity and never contributes to the score. It describes how new a package is, not whether it does anything.\n\nA verdict is a decision aid, not proof that a package is safe or malicious.\n\n## Usage\n\n```text\nnpx-vibe [options] <package-spec>                      # scan a package\nnpx-vibe run [options] <package-spec> [-- arguments]   # scan, then execute\nnpx-vibe approve-scripts [options] [--write]           # settle npm 12 allowScripts\nnpx-vibe --project <directory|package.json> [options]  # scan a dependency tree\nnpx-vibe --mcp\n```\n\nScanning never executes package code. `npx-vibe run` is the only command that\ndoes, and it still refuses a Block verdict unless you pass `--force`.\n\nCommon commands:\n\n```bash\n# Scan a package; nothing is executed\nnpx npx-vibe <package>\n\n# Machine-readable output\nnpx npx-vibe --json <package>\n\n# Versioned, fail-closed JSON for coding agents\nnpx --yes npx-vibe@latest --agent <package>\n\n# Review, then execute when permitted\nnpx npx-vibe run <package> -- <arguments>\n\n# Select one executable from a package with multiple binaries\nnpx npx-vibe run --bin tsc typescript -- --version\n\n# Decide which dependencies may run install scripts under npm 12\nnpx npx-vibe approve-scripts\nnpx npx-vibe approve-scripts --write\n\n# Scan production and optional dependencies from this project\nnpx npx-vibe --project .\n\n# Scan only the direct dependencies named in package.json\nnpx npx-vibe --project . --direct-only\n\n# Include direct development dependencies\nnpx npx-vibe --project . --include-dev\n\n# Machine-readable project report\nnpx npx-vibe --project . --json\n\n# Agent-ready project report\nnpx --yes npx-vibe@latest --agent --project .\n\n# Start the MCP server over stdio\nnpx --yes npx-vibe@latest --mcp\n\n# Execute a Caution verdict without prompting\nnpx npx-vibe run --yes <package>\n\n# Execute a Block verdict intentionally\nnpx npx-vibe run --force <package>\n```\n\nUseful options:\n\n```text\n--json\n--agent\n--mcp\n--project <path>\n--include-dev\n--direct-only\n--max-packages <1-5000>\n--no-advisories\n--ci\n--concurrency <1-8>\n--ai-limit <0-100>\n--yes, -y\n--force\n--bin <name>\n--ai off|auto|online|ollama\n--provider auto|openai|anthropic|gemini|openrouter|groq|together|custom\n--models\n--model <name>\n--api-key <key>\n--api-url <url>\n--ollama-url <url>\n--ollama-model <name>\n--registry <url>\n--age-days <days>\n--downloads <count>\n--caution-score <0-100>\n--block-score <0-100>\n--allow-install-scripts\n--no-history\n--history-file <path>\n--check                     (deprecated; scanning is the default and this is a no-op)\n--no-color\n```\n\nRun `npx npx-vibe --help` for the complete CLI reference.\n\n## Project dependency scans\n\nProject mode turns the one-package review into a repeatable dependency preflight:\n\n```bash\nnpx npx-vibe --project .\n```\n\nIt reads `package.json` and, when present, `package-lock.json` locally. Exact versions from npm lockfiles are preferred over version ranges. By default it scans direct `dependencies` and `optionalDependencies`; add `--include-dev` for `devDependencies`.\n\nEvery registry-resolved package in `package-lock.json` is reviewed, not only the direct ones, because supply-chain compromises usually arrive transitively. Pass `--direct-only` for the narrower, faster check:\n\n```bash\nnpx npx-vibe --project . --direct-only\n```\n\nWithout a lockfile the scan degrades to direct dependencies and says so, rather than failing.\n\n```text\n! npx-vibe project: Caution  highest risk 43/100\nmy-app@1.0.0\n\nScanned: 12/12 direct dependencies  Proceed: 11  Caution: 1  Block: 0\nScope: dependencies + optionalDependencies\nResolution: exact versions from package-lock.json when available\nAI review: off (heuristic-only)\n\nPackages:\n- CAUTION  43/100  esbuild@0.28.1\n  young_version, lifecycle_hook, network_and_shell\n\nNo dependency or package code was executed during this project scan.\nAction: review the flagged dependencies and their evidence individually.\n```\n\nThe workflow is deliberately bounded:\n\n- The whole installed tree from `package-lock.json` is scanned by default. `--direct-only` narrows it to the dependencies named in `package.json`.\n- `--max-packages` (default 500) caps how many packages one scan reviews. Anything past the cap is reported as skipped, never silently dropped.\n- Workspace, local, alias, URL, and Git specs are reported as skipped rather than uploaded or resolved through another trust path.\n- Heuristic-only scans use three concurrent reviews by default (`--concurrency 1-8`). Weekly download counts for the whole scan are fetched through npm's bulk endpoint in a single request.\n- If AI is opted in, reviews are sequential and only heuristic-triggered packages call the model. The default budget is three calls (`--ai-limit 0-100`).\n- `package.json` and `package-lock.json` are never sent to an AI provider. Optional online AI receives only bounded files selected from the downloaded registry package.\n\nThis is autonomous triage rather than autonomous execution: discover, resolve, verify, inspect, escalate when requested, and aggregate. It never installs dependencies or edits the project.\n\n## AI is optional and opt-in\n\nAmbient keys such as `OPENAI_API_KEY` or `GEMINI_API_KEY` do **not** activate AI in the default mode.\n\n> **Important:** Do not paste long-lived API keys into screenshots, issues, chat messages, or shared terminal recordings. Revoke any exposed key immediately.\n\n```bash\nnpx npx-vibe <package>                         # heuristic-only default\nnpx npx-vibe --provider gemini --api-key <key> <package>  # direct-key shortcut\nnpx npx-vibe --ai online <package>             # use an explicitly configured online provider\nnpx npx-vibe --ai auto <package>               # detect configured provider or local Ollama\nnpx npx-vibe --ai ollama <package>             # local Ollama\n```\n\nProvider-specific keys are read only after `--ai online` or `--ai auto` is selected:\n\n```bash\nOPENAI_API_KEY=... npx npx-vibe --ai online <package>\nANTHROPIC_API_KEY=... npx npx-vibe --ai online <package>\nGEMINI_API_KEY=... npx npx-vibe --ai online <package>\nOPENROUTER_API_KEY=... npx npx-vibe --ai online <package>\nGROQ_API_KEY=... npx npx-vibe --ai online <package>\nTOGETHER_API_KEY=... npx npx-vibe --ai online <package>\n```\n\nProvider-specific environment variables are the safest and most reliable option because they avoid provider guessing and keep secrets out of shell history. Recognizable direct-key formats can be routed automatically, but ambiguous formats stop locally and ask for `--provider` rather than sending a credential to a guessed service.\n\nGoogle introduced new Gemini authorization keys in June 2026. `npx-vibe 1.2.0` recognizes both the newer authorization-key family and traditional Google API keys, and sends Gemini credentials using Google's documented `x-goog-api-key` header.\n\nPowerShell example:\n\n```powershell\n$env:GEMINI_API_KEY=\"<new-key>\"\nnpx npx-vibe --ai online --provider gemini esbuild\nRemove-Item Env:GEMINI_API_KEY\n```\n\nDirect-key example when you intentionally want to specify the provider:\n\n```powershell\nnpx npx-vibe --provider gemini --api-key \"<new-key>\" esbuild\n```\n\nIf automatic routing cannot confidently identify a direct key, `npx-vibe` exits locally with instructions to add `--provider`. It does not try the key against OpenAI or any other guessed endpoint.\n\nCustom OpenAI-compatible endpoint:\n\n```bash\nnpx npx-vibe --ai online \\\n  --provider custom \\\n  --api-url https://models.example.com/v1/chat/completions \\\n  --api-key <key> \\\n  --model <model> \\\n  <package>\n```\n\nOnline AI receives bounded package metadata, deterministic findings, install scripts, and selected files from the downloaded package tarball. It does not receive your project files, shell history, npm tokens, or environment-variable values.\n\nAI findings are checked against the inspected source before they are displayed as evidence. A model finding records its file, line, exact excerpt, and rationale. Unsupported model claims are omitted from the source-backed findings section, and an unsupported AI recommendation cannot independently produce a Block verdict.\n\n### Naming the model is required\n\n`npx-vibe` ships **no model catalog**. A pinned model id rots: when a provider retires one, the call fails, the review becomes `ai_unavailable`, the score is floored, and the package reports a **false Caution**. A scanner whose accuracy decays on a timer is worse than one that asks you to name the model.\n\n```bash\nnpx npx-vibe --ai online --provider anthropic --model <id> <package>\nnpx npx-vibe --ai online --provider gemini --model <id> <package>\n```\n\n`--models` lists every supported provider, the environment variable it reads its key from, and where that provider publishes its current model list:\n\n```bash\nnpx npx-vibe --models\n```\n\nOfficial model lists: [OpenAI](https://platform.openai.com/docs/models), [Anthropic](https://docs.anthropic.com/en/docs/about-claude/models), [Gemini](https://ai.google.dev/gemini-api/docs/models), [OpenRouter](https://openrouter.ai/models), [Groq](https://console.groq.com/docs/models), and [Together](https://docs.together.ai/docs/serverless-models).\n\nLocal models need no key and keep their own default:\n\n```bash\nnpx npx-vibe --ai ollama --ollama-model qwen2.5-coder <package>\n```\n\n## Automation, agents, and CI\n\nUse JSON plus exit codes in local automation:\n\n```bash\nnpx npx-vibe --json <package> > npx-vibe-report.json\nnpx npx-vibe --project . --json > npx-vibe-project-report.json\n```\n\nUse the versioned agent envelope when another tool or coding agent owns the decision loop:\n\n```bash\nnpx --yes npx-vibe@latest --agent <package>\nnpx --yes npx-vibe@latest --agent --project .\n```\n\nAgent mode keeps stdout machine-readable for successful, incomplete, and failed scans. It is deliberately incompatible with `--force`, npx-vibe's `--yes`, `--allow-install-scripts`, and package execution arguments.\n\n### npm 12 migration guide\n\nnpm 12 turned install scripts off by default, and the hard part is not getting the\nlist of pending packages &mdash; it is deciding. **[npm 12 allowScripts: how to decide what to\napprove](https://devrajsinh-jhala.github.io/NPM-Vibe-check/npm-12-allowscripts.html)**\ncovers the three questions that matter, what the eight most common install-script\npackages actually do, the `.npmrc` setting that silently disables the whole\nallowlist system, and how to enforce the result in CI.\n\n### GitHub Action\n\n[Listed on the GitHub Marketplace](https://github.com/marketplace/actions/npx-vibe). The action wraps the same CLI, so a workflow needs one step:\n\n```yaml\nname: Dependency preflight\n\non: [pull_request]\n\njobs:\n  preflight:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v6\n      - uses: actions/setup-node@v6\n        with:\n          node-version: 24\n      - uses: Devrajsinh-Jhala/NPM-Vibe-check@v2\n```\n\nReview install-script permissions instead of the dependency tree, and fail the\nbuild when a lockfile change introduces one you have not decided on:\n\n```yaml\n      - uses: Devrajsinh-Jhala/NPM-Vibe-check@v2\n        with:\n          command: approve-scripts\n          fail-on: caution\n```\n\n| Input | Default | Purpose |\n| --- | --- | --- |\n| `command` | `project` | `project`, `approve-scripts`, or `package` |\n| `package` | | Package spec, required when `command: package` |\n| `path` | `.` | Project directory or `package.json` path |\n| `include-dev` | `false` | Include devDependencies in a project scan |\n| `direct-only` | `false` | Skip the transitive tree |\n| `max-packages` | `500` | Cap on packages reviewed in one run |\n| `fail-on` | `block` | `block`, `caution`, or `never` |\n| `version` | `2` | npx-vibe version range to run |\n\nOutputs are `verdict` (`proceed`, `caution`, `block`, `error`) and `exit-code`.\nAn incomplete scan always fails the step, even with `fail-on: never` &mdash; a scan\nthat could not finish is never read as a pass.\n\nFor GitHub Actions, `--ci` emits a warning for each Caution result, an error for each Block or operational failure, and writes a package table to the job summary:\n\n```yaml\nname: Dependency preflight\n\non:\n  pull_request:\n  workflow_dispatch:\n\njobs:\n  npx-vibe:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: 20\n      - run: npx --yes npx-vibe@2.0.0 --project . --include-dev --ci\n```\n\nProject mode preserves the normal exit contract: `0` Proceed, `2` Caution, `3` Block, and `1` for an incomplete scan caused by an operational error. `--ci` and `--json` are intentionally separate so JSON output remains valid.\n\nThe repository tests Node.js 20, 22, and 24 across Linux, Windows, and macOS. CI also packs the npm tarball, installs it into a clean temporary consumer project, and exercises the shipped CLI and MCP handshake from the exact artifact users receive.\n\nThe tag-driven release workflow is prepared for [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) and `npm publish --provenance`. Configure the trusted publisher once, then push a version tag to publish without storing a long-lived npm token. See [RELEASING.md](./RELEASING.md).\n\n## Configuration\n\n```bash\nNPX_VIBE_AI=off\nNPX_VIBE_PROVIDER=auto\nNPX_VIBE_API_KEY=...\nNPX_VIBE_API_URL=https://api.openai.com/v1/chat/completions\nNPX_VIBE_MODEL=                # required for online AI review\nNPX_VIBE_HISTORY=on\nNPX_VIBE_HISTORY_FILE=~/.npx-vibe/reviews.json\nNPX_VIBE_OLLAMA_URL=http://127.0.0.1:11434\nNPX_VIBE_OLLAMA_MODEL=qwen2.5-coder\nNPX_VIBE_AGE_DAYS=14\nNPX_VIBE_DOWNLOADS=1000\nNPX_VIBE_CAUTION_SCORE=40\nNPX_VIBE_BLOCK_SCORE=70\nNPX_VIBE_CONCURRENCY=3\nNPX_VIBE_AI_LIMIT=3\nNPX_VIBE_MAX_PACKAGES=500\nNPX_VIBE_ADVISORIES=on         # \"off\" skips the OSV lookup\nGITHUB_TOKEN=                # optional; raises the GitHub metadata rate limit\n```\n\n## Supported scope\n\n`npx-vibe` supports public npm registry package names, scoped packages, dist-tags, exact versions, common semver ranges, and dependency discovery from npm package manifests and lockfiles, including the full transitive tree with `--transitive`. Version ranges resolve to stable releases unless the range itself names a prerelease, matching npm. It intentionally rejects local paths, arbitrary tarball URLs, Git URLs, and non-registry project dependencies to keep the trust boundary narrow.\n\nNode.js 20 or newer is required. The project is tested on current Windows, macOS, and Linux GitHub-hosted runners.\n\n## Security boundary\n\n`npx-vibe` is a pre-execution risk scanner. It is not a sandbox, antivirus engine, formal audit, or guarantee of safety. A package may hide behavior in unselected files, runtime branches, native code, or remote responses.\n\nReview coverage is bounded and reported rather than implied. Files are selected from the install and executable entry points and the imports reachable from them; each selected file is read up to 64 KiB, and the scan stops selecting once the byte budget is reached. The dashboard names how many files were read only in part or left past the budget, so a large bundled file is never mistaken for a fully reviewed one.\n\n- Treat **Proceed** as a useful signal, not proof.\n- Read the evidence for **Caution** findings.\n- Do not bypass **Block** unless you understand the behavior.\n- Report vulnerabilities privately through [SECURITY.md](./SECURITY.md).\n- Report noisy findings with the [false-positive template](https://github.com/Devrajsinh-Jhala/NPM-Vibe-check/issues/new?template=false-positive.yml).\n\n## Contributing\n\nContributions that improve detection quality, evidence, compatibility, or false-positive handling are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## License\n\nMIT © Devrajsinh Jhala\n",
  "bytes": 28585,
  "sha": "a0d3ae87408d0ab914b97ac38e6b39bb8e3fb3d4b129c53a126248eb3515a9a2",
  "repo_slug": "devrajsinh-jhala/npm-vibe-check",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_devrajsinh_jhala_npx_vibe_a813d96d/readme"
}