io.github.CloudCorpRecords/pkgverdict

pkgverdict

Check an npm package before you install it. One command, one verdict: GO, RISKY, FAKE, or MISSING — in plain words your AI coding agent can read too.

npx -y pkgverdict check react-markdown
# [GO] react-markdown@10.1.0
#   - established, 38.4M/wk, no install scripts, no advisories, no lookalike name.

npx -y pkgverdict check unused-imports
# [FAKE] unused-imports@0.0.1-security
#   - Flagged malicious: MAL-2025-48781. Do not install.
#   - Name rides on eslint-plugin-unused-imports (suffix of popular name) and the
#     package is barely downloaded — the classic typosquat shape.

npx -y pkgverdict check react-super-hooks-plus
# [MISSING] react-super-hooks-plus
#   - react-super-hooks-plus is not on the npm registry. If an AI assistant
#     suggested it, the name was hallucinated.

Why

AI assistants now pick half the packages developers install — and they hallucinate names attackers have already registered (slopsquatting), while typosquats and hijacked releases keep shipping postinstall malware. npm audit only sees published advisories, after the fact. pkgverdict checks before the install: existence, lookalike names, package age, install scripts, maintainers, downloads, and OSV advisories.

Use it inside your AI coding tool

One command sets it up. In your project directory, run:

npx -y pkgverdict init --agent claude-code

That installs the MCP server config plus the instruction snippet teaching your agent the one behavior rule: check pkgverdict before installing. Supported tools: claude-code, cursor, copilot (VS Code), windsurf, cline, and generic (init --list shows them all; --all sets up everything; --dry-run previews without writing). Restart your tool, verify with a "list your MCP tools" prompt, and the pkgverdict server should appear with 2 tools (check_package, scan_dependencies). The underlying pack lives in integrations/ if you prefer to install by hand.

CLI

# Verdict on one package (name or name@version)
npx -y pkgverdict check lodash

# Check every dependency in package.json, worst first
npx -y pkgverdict scan
npx -y pkgverdict scan ./my-app --no-dev

# Check your setup (Node version, registry + OSV reachability, cache)
npx -y pkgverdict doctor

# JSON output for scripting and CI
npx -y pkgverdict check left-pad --json

Exit codes: 0 when everything is GO (or RISKY without --strict), 1 when a FAKE or MISSING package is found, 2 on usage errors. For CI gates that should fail on anything suspicious: pkgverdict scan --strict.

Verdicts

Verdict	Meaning
GO	Established package, no red flags. Install away.
RISKY	Caution: install scripts, very young, obscure, deprecated, no repo/license, known advisories, or a lookalike name on an otherwise fine package. Read before installing.
FAKE	Looks actively bad: typosquat-shaped name on a new/obscure package, hostile install script, or a malicious (MAL-) advisory. Do not install.
MISSING	Not on the registry at all — a typo or a hallucinated name, with a "did you mean" suggestion when one fits.

Signals come from the npm registry (metadata, downloads), the OSV database (advisories), and a bundled list of well-known packages for lookalike detection. Responses cache under ~/.cache/pkgverdict (6h metadata, 1h advisories); delete that directory to force fresh checks.

Run it with Docker

pkgverdict also ships as a container image on GHCR: ghcr.io/cloudcorprecords/pkgverdict.

Use it as a stdio MCP server:

docker run -i ghcr.io/cloudcorprecords/pkgverdict

Any CLI command can be passed after the image name instead of the default mcp argument:

docker run ghcr.io/cloudcorprecords/pkgverdict <command> [args]

MCP server

Run it with npx -y pkgverdict mcp (stdio), or point your agent at the pkgverdict command with the single argument mcp. Two tools: check_package (verdict on one package) and scan_dependencies (worst-first verdicts for a project's package.json).

Development

npm install
npm run build
npm test        # offline fixture corpus: every verdict rule pinned to a case

License

MIT.