# npx-vibe

> Evidence-first npm package and project dependency checks before code executes.

npx-vibe is a zero-runtime-dependency Node.js CLI and MCP server that resolves public npm packages, downloads and verifies registry tarballs without executing package code, inspects install-time behavior, and reports Proceed, Caution, or Block with source evidence.

## Canonical links

- Website: https://devrajsinh-jhala.github.io/NPM-Vibe-check/
- npm: https://www.npmjs.com/package/npx-vibe
- Source and documentation: https://github.com/Devrajsinh-Jhala/NPM-Vibe-check
- Agent Skill: https://github.com/Devrajsinh-Jhala/NPM-Vibe-check/tree/master/skills/npx-vibe
- Security policy: https://github.com/Devrajsinh-Jhala/NPM-Vibe-check/blob/master/SECURITY.md

## Agent-safe commands

Inspect one package with versioned JSON output:

    npx --yes npx-vibe@latest --agent <package-spec>

Inspect direct registry dependencies in the current project:

    npx --yes npx-vibe@latest --agent --project .

Install the portable Agent Skill:

    npx skills add Devrajsinh-Jhala/NPM-Vibe-check --skill npx-vibe -g

## MCP server

Start the local stdio server:

    npx --yes npx-vibe@latest --mcp

Dedicated global binary:

    npx-vibe-mcp

Tools:

- scan_package: inspect one public npm package
- scan_project: inspect direct registry dependencies in a project
- list_models: inspect bundled provider/model recommendations

MCP scan results return the same schemaVersion 1 decision envelope in structuredContent and a JSON text block. Tools are read-only and do not accept API keys as arguments. AI is off by default; credentials must be configured in the MCP server environment. The active official MCP Registry identifier is io.github.Devrajsinh-Jhala/npx-vibe: https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Devrajsinh-Jhala%2Fnpx-vibe

## Decision contract

- schemaVersion: currently 1
- decision.action=continue: the requested workflow may continue
- decision.action=review: pause and request human review
- decision.action=stop: do not install or execute
- decision.action=retry: the scan was incomplete; fail closed
- exit codes: 0 Proceed, 2 Caution, 3 Block, 1 operational error or incomplete project scan

AI review is off by default. Online or local AI is opt-in and never replaces deterministic evidence. A Proceed verdict is a review signal, not proof that a package is safe.