Agents install fresh versions within hours of release. So do worms.

package-guidance is an agent skill, a CLI and a Claude Code hook. Before your agent adds a dependency, it checks the live registry, pins the newest settled version (7+ days old, no known advisories), refuses names that don’t exist, and points to the migration when a package is dead.

npx skills add harshpreet931/package-guidance

On Claude Code, the plugin also adds an install hook. Works with Cursor, Codex and anything that reads AGENTS.md.

release board npm · cooldown 7d
  1. next16.4.66dhold 1d
  2. next16.4.512dcleared
  3. sass1.108.25dhold 2d
  4. sass1.108.19dcleared
  5. date-fns4.4.0170dcleared
  6. lodash4.17.202 high/crituse 4.18.1
  7. reqeusts-pro—not on npmnot found
  8. request—since 2020deprecated
Verdicts from package-guidance check on 2026-11-16. A release younger than 7 days is held; the agent installs the newest one that has settled.

Same request. One agent checks first.

Asked to add an HTTP client, date handling and Sass, an agent types what it remembers. With package-guidance it asks the registry, swaps the dead packages, and pins what has settled.

agent, unguided 15 vulnerabilities
agent › Adding an HTTP client, date handling and Sass.
$ npm i request moment node-sass
npm warn deprecated inflight@1.0.6: This module is not supported, and leaks memory…
npm warn deprecated har-validator@5.1.5: this library is no longer supported
npm warn deprecated glob@7.2.3: Old versions of glob are not supported, and contain widely publicized security vulnerabilities…
npm warn deprecated request@2.88.2: request has been deprecated, see https://github.com/request/request/issues/3142
npm warn deprecated tar@6.2.1: Old versions of tar are not supported, and contain widely publicized security vulnerabilities…
npm warn deprecated node-sass@9.0.0: Node Sass is no longer supported. Please use `sass` or `sass-embedded` instead.
# 9 more deprecation warnings

added 247 packages, and audited 248 packages in 6s

15 vulnerabilities (2 low, 3 moderate, 7 high, 3 critical)
agent + package-guidance 0 vulnerabilities
agent › Checking these before I add anything.
$ npx package-guidance check request moment node-sass

  package-guidance  npm · cooldown 7d

  ✗ request    deprecated   request has been deprecated since Feb 2020…
                            use fetch (native), ky, ofetch · guide: request-to-fetch
  → moment     replace      Moment is a legacy project in maintenance mode (status update…
                            use date-fns, Temporal (native), dayjs · guide: moment-to-date-fns
  ✗ node-sass  deprecated   node-sass (LibSass) is deprecated: 'Node Sass is no longer…
                            use sass, sass-embedded · guide: node-sass-to-sass

  Blocked  request, node-sass  do not install; use the alternatives above

agent › Native fetch instead of request. Checking date-fns and sass.
$ npx package-guidance check date-fns sass

  package-guidance  npm · cooldown 7d

  ✓ date-fns  ok   4.4.0 · settled 170d
  ✓ sass      ok   1.108.1 · settled 9d
                   1.108.2 was published 5d ago; holding at 1.108.1 until it settles (7d…

  Install  npm install date-fns@4.4.0 sass@1.108.1

$ npm install date-fns@4.4.0 sass@1.108.1

added 13 packages, and audited 14 packages in 2s

found 0 vulnerabilities

Every $ command and its output is a real capture from 2026-11-16, trimmed where marked. “agent ›” lines are narration. The unguided install ran with --ignore-scripts, so node-sass skipped its native build.

Agents guess. The registry doesn’t.

Models learn package names and versions from a frozen snapshot of the internet, then type them into your terminal as if they were current.

  1. 27.76%

    of GPT-5’s dependency upgrade recommendations pointed to versions that don’t exist. Across 36,870 recommendations on Maven Central, npm, PyPI and NuGet, that was more than 10,000 hallucinated releases.

    Sonatype, State of the Software Supply Chain 2026

  2. 21.7%

    of packages suggested by open-source models don’t exist, and at least 5.2% for commercial models, across 576,000 generated code samples from 16 models. Anyone can register a hallucinated name and wait for an agent to install it. That is slopsquatting.

    Spracklen et al., USENIX Security 2025

  3. 2.46%vs 1.64%

    of dependency changes picked a known-vulnerable version: AI agents versus humans, across 117,062 changes in 2,807 GitHub repositories. In most cases a patched version already existed.

    arXiv:2601.00205, Understanding Security Risks of AI Agents’ Dependency Updates

Latest isn’t safe. Settled is.

Compromised releases are published as the latest version and usually get pulled within hours. An agent that installs @latest the minute it ships is exactly who those hours are for. A 7-day cooldown skips the whole window.

known compromise
chalk, debug + others · Sep 8, 2025 · live ≈2h
plain agent

39 dots between 15 hours and 6.99 days old. Youngest: nodemailer 10.6.0 at 15 hours. Most common: vite 8.3.8, installed 5 times at 5.3 days. Oldest: vite 7.3.8 at 6.99 days.

nodemailer 10.6.0 · 15h vite 7.3.8 · 6.99d
with package-guidance
0 versions under 7 days
Installing at 7d settled Past the cooldown. This is the version package-guidance pins, unless a newer release fixes an advisory.
Release age on a linear scale. Red: the hijacked chalk/debug releases were live from about 13:16 to 15:15 UTC on September 8, 2025, per Wiz. Dots: each of the 39 versions younger than 7 days that a plain Claude Sonnet agent added in our eval, placed at its real age at install time. The Nov 2025 Shai-Hulud 2.0 worm pushed malicious versions of hundreds of packages; exposure varied by package, so it isn’t plotted. Drag the handle, or use the arrow keys.

pnpm, npm, yarn, bun and uv can enforce a release-age cooldown themselves. package-guidance harden sets it up for your repo, and the hook respects it.

Seven checks before any install

The skill gives your agent one procedure to run before it adds a dependency. The CLI does the lookups against live registry data, so the agent never relies on memory.

  1. 1

    Need it?

    Prefer the platform: fetch, crypto.randomUUID(), structuredClone, node --env-file, zoneinfo. Fewer dependencies, fewer attack surfaces.

    replace
  2. 2

    Right package?

    Not deprecated, sunset or superseded. Curated entries plus the e18e module-replacements dataset and the registry’s own flag.

    deprecatedoutdated
  3. 3

    Real package?

    A registry 404 means a hallucination. Never install it, and never guess a similar name.

    not-foundunproven
  4. 4

    Settled version

    The newest release at least 7 days old. A newer one only if it fixes an advisory on the older one.

    youngok
  5. 5

    No known advisories

    The pinned version is checked against OSV.dev, which includes malicious-package reports.

    vulnerablemalicious
  6. 6

    Respect project policy

    If the repo configures a release-age cooldown, keep it. Never lower, remove or bypass it to make an install succeed.

  7. 7

    Pin exactly

    Install pkg@1.2.3 or pkg==1.2.3 and commit the lockfile.

    install

62 sessions without it. 62 with it.

31 real tasks (add auth, modernize a CRA app, set up linting, add a database…), each run twice per arm in Claude Code with Claude Sonnet. An independent scorer graded every dependency using public npm, PyPI and OSV data only, never package-guidance itself.

Dependencies the agent added or changed, 62 sessions per arm plain agent with package-guidance
Versions published less than 7 days earlier 39 0
Versions with a known advisory (2 high/critical) 7 0
Sessions with zero dependency problems 47% 92%
Problem dependencies per session 1.08 0.15
Whole repo, every direct dependency: problem dependencies per session
3.16 → 2.11
Whole repo: sessions with zero issues
27% → 45%
Direct dependencies pinned exactly
13% → 77%
Hallucinated packages (registry 404)
0 → 0
Agent cost per session
$0.15 → $0.18

Whole-repo numbers include dependencies the task fixtures already had, such as an old next or eslint the agent wasn’t asked to touch. No session in either arm installed a hallucinated package on these tasks, so we make no claim about hallucinations here. Each delta has a 95% bootstrap interval in the full report; the method and threats to validity are in the repo.

Install for every agent

It is one skill file. Use whichever loader your agent already has.

Installs the skill into any agent the skills CLI supports: Claude Code, Codex, Cursor, Copilot, Gemini CLI and more.

npx skills add harshpreet931/package-guidance

The CLI

Zero runtime dependencies. The agent calls it, and so can you. It exits with 1 when anything is blocked, so scan works in CI.

check <pkg[@range]>…
A verdict and a pinned install line for each package. Add --pypi for Python.
scan [dir]
Audits package.json, pyproject.toml or requirements.txt.
guide [id | query]
Curated migrations: CRA to Vite, Tailwind v4, ESLint flat config, moment to date-fns.
harden [dir] [--write]
Sets a release-age cooldown in your package manager’s own config: npm, pnpm, Yarn, Bun or uv.
hook
The Claude Code PreToolUse handler (stdin JSON).
Options
--cooldown <days> --json --cwd <dir> --no-cache -v
terminal
$ npx package-guidance check request moment tailwindcss@3 lodash@4.17.20 reqeusts-pro next

  package-guidance  npm · cooldown 7d

  ✗ request         deprecated   request has been deprecated since Feb 2020…
                                 use fetch (native), ky, ofetch · guide: request-to-fetch
  → moment          replace      Moment is a legacy project in maintenance mode (status…
                                 use date-fns, Temporal (native), dayjs · guide: moment-to-date-fns
  ! tailwindcss@3   outdated     Tailwind v4 is current (4.3.x).
                                 use tailwindcss@4, @tailwindcss/postcss, @tailwindcss/upgrade · guide: tailwind-v4
  ✗ lodash@4.17.20  vulnerable   Use 4.18.1: 4.17.20 has 2 high/critical advisories.
                                 high     GHSA-35jh-r3h4-6jhm  Command Injection in lodash
                                 high     GHSA-r5fr-rjxr-66jc  lodash vulnerable to Code Injection via `_.template` imports…
                                 +2 more (-v)
                                 lodash is maintained, but much of it is native now…
  ✗ reqeusts-pro    not-found    Likely hallucinated: not on the npm registry.
  ✓ next            ok           16.4.5 · settled 12d
                                 16.4.6 was published 6d ago; holding at 16.4.5 until it…

  Install  npm install tailwindcss@4.3.5 lodash@4.18.1 next@16.4.5

  Blocked  request, reqeusts-pro  do not install; use the alternatives above
Real output, 2026-11-16, at COLUMNS=96. Versions move daily; that is the point.
okInstall the pinned version.
cautionInstallable, with a known risk worth reading.
outdatedThe requested range is on an old major.
replaceUse one of the alternatives, native APIs first.
deprecatedDeprecated on the registry or sunset by its maintainers.
vulnerableHigh/critical advisories; fixedIn is the settled fix.
maliciousOSV reports this release as malware.
not-foundThe package or version doesn’t exist. Almost always a hallucination.
young · unprovenBrand-new or barely downloaded. Confirm it’s the real one.

Questions

Something wrong or missing? Open an issue.

Isn’t this what Socket, Snyk and Dependabot do?

They are excellent, and they run after the choice: in CI, on a PR, or on a package the agent already picked. package-guidance runs at the moment of choice, inside the agent, and tells it what to pick instead. Use both.

Doesn’t “latest” mean “safest”?

No. @latest is exactly where compromised releases appear first, and they are usually pulled within hours. The hijacked chalk and debug releases were live for about two hours. Waiting 7 days skips that window; the only exception is a newer release that fixes an advisory on the version you would otherwise pin.

Do you follow your own advice?

Yes. The skill and the hook run an exact pinned version of this tool (package-guidance@0.1.0), never @latest. Our GitHub Actions are pinned to commit SHAs and respect the cooldown too.

Does it send telemetry?

No. The only network calls are public lookups: deps.dev, the npm and PyPI registries, OSV.dev and npm download counts. No API keys. Responses are cached for an hour in ~/.cache/package-guidance.

Will it slow my agent down?

A check takes about a second cold and is near-instant from cache. The hook does nothing unless a command installs packages, and costs about 25 ms when it doesn’t.

What if the registry is down, or I use a private one?

The hook fails open: a network error or timeout never blocks you. It never denies a 404 on a private registry.

Python?

Yes. Add --pypi: npx package-guidance check --pypi "pydantic<2" fastapi. The hook understands pip, uv and poetry.