Stop AI Hallucinating Packages (It Almost Installed Malware)

npm install for a package that never existed

The agent finishes the feature, the code looks clean, and npm run build dies: Cannot find module 'stripe-event-normalizer'. No such package exists. The agent invented it — plausible name, correct-looking API, total fiction.

This is the most common agent failure in JavaScript: models trained on millions of repos autocomplete import statements the way they autocomplete sentences — confidently, sometimes fictionally. And npm install obeys without judgment, pulling typosquat malware when the invented name happens to be registered by someone malicious.

Stop AI hallucinating packages is not a model problem you can prompt away. It is a process problem with a three-rule fix.

Phantom deps vs real supply chain

Three details make invented packages worse than wasted minutes:

1. Typosquats wait for typos. Attackers register the exact plausible names agents invent. The agent that hallucinates resend-edge-client may find it installable — owned by a stranger running a postinstall script. Fiction becomes intrusion in one command.
2. Each dep is a stranger's code in prod. The average agent-added package pulls dozens of transitive deps. Every one runs with your Stripe keys in scope. Fewer deps is not minimalism — it is access control.
3. Lockfile churn hides the crime. Ten sessions each adding "one small package" produce a lockfile nobody reads. The phantom hides among the real, and npm audit reports on fiction it cannot see.

The hallucinated-packages post told the war story. This one installs the prevention.

The 3-rule file plus the ritual

BoringPush ships this as part of AGENTS.md — the zero-dependency law, enforced by the gate and the lockfile.

Step 1 — Write the three rules where the agent reads them.

## Dependencies (never violate)

1. Never run npm install or add packages without a written argument
   (what, why, what breaks without it) approved by a human.
2. Every import must resolve to package.json + lockfile — if it is not
   listed, it does not exist. No exceptions, no "try installing."
3. Node and Next built-ins first: fs, fetch, crypto, AsyncLocalStorage,
   Server Components, Route Handlers. Nine times in ten, no package needed.

Rule 2 is the phantom-killer: it flips the default from "install what I import" to "imports must pre-exist." An agent that invents stripe-event-normalizer now fails its own rule before touching the network — the fiction dies at the whiteboard instead of in node_modules.

Step 2 — Run the 30-second pre-install ritual for the tenth time.

# human runs this before approving any new dep:
npm view <name> time --json | tail -5   # exists? maintained?
npm view <name> dependencies --json      # what does it drag in?
npx --dry-run -p <name> 2>&1 | head -3   # sanity, no install

Five lines that answer: real or phantom, alive or abandoned, lean or bloated. The ritual takes thirty seconds and has killed every phantom before install — including two typosquat near-misses where the name existed but the owner was three weeks old with zero dependents.

Step 3 — Audit the lockfile monthly like a dependency diet.

npx depcheck        # find imports nobody uses
npm ls --depth=0    # what do we actually depend on
# remove one unused dep per month — momentum beats purges

depcheck names the dead weight agents left behind; one removal per month keeps the list honest without purge-day drama. Fewer deps mean fewer postinstall scripts, fewer advisories, faster builds — and a smaller blast radius the next time an agent gets creative.

That's the arrangement — the dependency list fits in memory, and phantoms never board.

Before and after the 3-rule file

Full disclosure: the ritual taxes genuine needs — occasionally a session waits hours for a human to approve a truly necessary package.

BoringPush accepts the delay because the default direction matters: friction on adding, none on removing. Dependencies should be hard to adopt and easy to divorce. Most repos have it exactly backwards.

FAQ

How do I stop ai hallucinating packages in editors without AGENTS.md support?

Put the same three rules in whatever instruction file the tool reads (project rules, workspace instructions, .cursorrules) and add the lockfile check to your own review habit: git diff --stat package.json on every agent session, before anything else. The file location varies by tool; the rule content never does. One source of truth, symlinked everywhere.

What if the agent needs a package for a genuinely hard problem?

Then it writes the argument: problem, candidate, why built-ins fail, transitive cost, maintenance evidence (npm view output pasted in). You read five lines and approve or redirect. Nine times in ten the redirect works (fetch instead of axios, Web Crypto instead of a lib, Route Handlers instead of a framework). The tenth time, you gain a dependency deliberately — with its reason committed beside it.

Are lockfiles enough protection without the rules?

No — lockfiles record decisions, they do not make them. A phantom installed once enters the lockfile like a legitimate resident, and every later npm ci faithfully reproduces the fiction (or the malware). Rules prevent entry; lockfiles preserve state. You need the bouncer and the ledger, in that order.

Should I use npm audit or a scanner instead of rituals?

Both, layered: the ritual prevents entry, monthly depcheck removes dead weight, and npm audit watches what remains. Scanners report on known-bad residents; they cannot judge whether a resident should live there at all. Prevention (rules), hygiene (audits), surveillance (scanners) — three jobs, three tools, no substitutes.

How do transitive dependencies factor into approval?

npm view <name> dependencies is step two of the ritual for exactly this reason: a 5KB utility dragging 40MB of transitive tree fails the leanness test. Prefer zero-dependency packages (check dependencies: {} in the manifest) and treat every transitive stranger as your own attack surface — because at runtime, with your env keys loaded, it is.

What about frontend component libraries the agent loves adding?

Same rules, stricter stakes: UI kits import hundreds of components to use three, bloat the client bundle, and stamp a foreign design language over yours. Pin Tailwind plus inline SVG and forbid component libraries by rule — every agent-built screen stays coherent, light, and reviewable.

Keep reading

• Claude Hallucinated a Package That Doesn't Exist — the war story behind these rules
• OpenCode SaaS Starter: Stop the Every-Session Redesign — the file these rules live in
• Will Claude Code Respect Your Boilerplate? 6 Tests — the scorecard that grades dependency discipline