npx-vibe

Evidence-first safety checks for npm packages and project dependencies before developers, coding agents, or MCP clients execute them.

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.

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

• npm package
• Official MCP Registry entry
• Live website
• GitHub repository
• Security policy
• Changelog
• Release process

Live adoption

The project website displays the current seven-day download total directly from npm's public download API:

• weekly total
• daily seven-day range

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

Quick start

Review a package without executing it:

npx npx-vibe esbuild

Use it as a guarded replacement for npx:

npx npx-vibe cowsay -- hello from npx-vibe

Or install the command globally:

npm install -g npx-vibe
npx-vibe <package>

Scan an existing project's direct dependencies:

npx npx-vibe --project .

Give a coding agent a stable, read-only result:

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

Or connect the native MCP server:

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

Use npx-vibe with coding agents

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

Install the portable Agent Skill for Codex, Claude Code, Cursor, VS Code, and other compatible agents:

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

The skill tells an agent to preflight unfamiliar packages before npx, npm exec, or dependency installation and then apply the normalized decision:

Example envelope:

{
  "schemaVersion": 2,
  "tool": { "name": "npx-vibe", "version": "2.0.0" },
  "kind": "package-scan",
  "status": "complete",
  "decision": {
    "verdict": "caution",
    "riskScore": 43,
    "action": "review",
    "exitCode": 2,
    "mayContinue": false,
    "safeToExecute": false,
    "requiresApproval": true,
    "requiresHumanReview": true,
    "blocked": false,
    "mustStop": false
  },
  "subject": {
    "type": "package",
    "name": "esbuild",
    "requested": "latest",
    "version": "0.28.1"
  },
  "report": {}
}

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

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

Connect npx-vibe through MCP

Version 1.5 includes a read-only Model Context Protocol server over stdio. It gives MCP-compatible AI applications a native tool surface without teaching them to parse terminal text or construct shell commands.

Add this server configuration to an MCP client that supports local stdio servers:

{
  "mcpServers": {
    "npx-vibe": {
      "command": "npx",
      "args": ["--yes", "npx-vibe@latest", "--mcp"]
    }
  }
}

Global installations can use npx-vibe-mcp as the command with no arguments. Run npx npx-vibe --mcp --help for server-specific help.

The server exposes four schema-backed tools:

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

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

npx-vibe@2.0.0 is active in the official MCP Registry as io.github.Devrajsinh-Jhala/npx-vibe. Registry clients can resolve the verified npm package and start its local stdio server with --mcp.

Why developers use it

Running npx some-package can download code and execute a package binary immediately. Packages may also declare lifecycle scripts that run during installation.

npx-vibe inserts a visible checkpoint before execution:

1. Resolve the exact npm package version.
2. Fetch registry, download, maintainer, publisher, and repository context.
3. Download the tarball without running package code.
4. Verify npm integrity metadata and inspect bounded source files.
5. Show matched evidence and a risk verdict.
6. Execute only after the verdict allows it.

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

By default, execution uses npm with install scripts ignored. Use --allow-install-scripts only when you intentionally want reviewed root lifecycle scripts to run.

Evidence, not mystery scores

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

$ npx npx-vibe esbuild
! npx-vibe: Caution  risk 43/100
esbuild@0.28.1

Downloads: 241,858,907/week  Package age: 3132d  Version age: 12d
Install hooks: postinstall
Established signals: long registry history, high weekly adoption, linked GitHub repository
Registry popularity and age provide context, but never override code findings.
Review memory: unchanged tarball since 2026-06-25; previous Caution 43/100.
AI review: skipped (Heuristic-only mode; AI was not requested.)

Findings:
- MEDIUM   lifecycle_hook in package.json
  postinstall runs: node install.js
  Evidence: postinstall: node install.js
- MEDIUM   network_and_shell in install.js
  Code combines network access with shell execution.
  Evidence line 147: fetch(url) ... child_process.execSync(...)

Action: review recommended before execution.

A popular package can still receive Caution when it performs sensitive install-time behavior. That is intentional: maturity is useful context, not a security exemption.

When 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:

$ npx npx-vibe --ai online --provider gemini --model gemini-3.5-flash esbuild
! npx-vibe: Caution  risk 43/100
esbuild@0.28.1