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.
- next16.4.66dhold 1d
- next16.4.512dcleared
- sass1.108.25dhold 2d
- sass1.108.19dcleared
- date-fns4.4.0170dcleared
- lodash4.17.202 high/crituse 4.18.1
- reqeusts-pro—not on npmnot found
- request—since 2020deprecated
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 › 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 › 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.
-
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.
-
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.
-
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.
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.99dchalk/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.
- 1replace
Need it?
Prefer the platform:
fetch,crypto.randomUUID(),structuredClone,node --env-file,zoneinfo. Fewer dependencies, fewer attack surfaces. - 2deprecatedoutdated
Right package?
Not deprecated, sunset or superseded. Curated entries plus the e18e module-replacements dataset and the registry’s own flag.
- 3not-foundunproven
Real package?
A registry 404 means a hallucination. Never install it, and never guess a similar name.
- 4youngok
Settled version
The newest release at least 7 days old. A newer one only if it fixes an advisory on the older one.
- 5vulnerablemalicious
No known advisories
The pinned version is checked against OSV.dev, which includes malicious-package reports.
- 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.
- 7install
Pin exactly
Install
pkg@1.2.3orpkg==1.2.3and commit the lockfile.
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.
- 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.
- Claude Sonnetdone · 124 runs
- Claude Opusdone · 30 runs · 12 fresh installs → 0, 100% clean
- Kimidone · 182 scored answers · 49 fresh pins → 0; a registry tool alone: 48
- GLMincomplete · gateway failures, rerun pending
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-guidanceThe plugin adds the skill and a PreToolUse hook on Bash. The hook denies hallucinated, malicious, deprecated and known-vulnerable installs, and unpinned installs whose latest release is inside the cooldown. It never approves anything, fails open on network errors, and costs about 25 ms on commands that install nothing.
/plugin marketplace add harshpreet931/package-guidance
/plugin install package-guidance@package-guidanceSet PACKAGE_GUIDANCE_HOOK=warn to never deny, or off to disable the hook.
The same skills CLI, pointed at one agent.
npx skills add harshpreet931/package-guidance --agent cursor
npx skills add harshpreet931/package-guidance --agent codexCopy copies the Cursor line. Or paste the AGENTS.md snippet into .cursor/rules.
No loader? Paste this into AGENTS.md, CLAUDE.md or .cursor/rules.
## Dependencies
Before adding or upgrading any npm or PyPI package, run
`npx -y package-guidance@0.1.0 check <pkg>... --json` (add `--pypi` for Python) and install the
returned `install` command verbatim. Never install `not-found`, `deprecated`, `malicious` or
unfixed `vulnerable` packages, never guess a similar name, and never lower a configured
release-age cooldown.The snippet pins package-guidance@0.1.0 on purpose. We don’t tell agents to run @latest either.
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
--pypifor Python. scan [dir]- Audits
package.json,pyproject.tomlorrequirements.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
PreToolUsehandler (stdin JSON). - Options
--cooldown <days>--json--cwd <dir>--no-cache-v
$ 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
COLUMNS=96. Versions move daily; that is the point.fixedIn is the settled fix.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.