---
title: I shipped the new major, agents still installed the old one: a 2-minute npm check
date: 2026-11-16
tags: [npm, coding-agents, deprecation, package-rename, documentation, agent-readiness]
type: success
status: n/a
reproducible: true
visibility: public
stack: npm packages (JavaScript / TypeScript) · Claude Code · Codex CLI · Gemini (Antigravity)
agent: Claude Code
model: claude-opus-5-5
---

# I shipped the new major, agents still installed the old one: a 2-minute npm check

When a user asks a coding agent for "the current version" of a library, the agent checks npm first and often never reaches your docs site. Whatever npm shows it in the first minute usually ends up in the user's code, and the agent then tells the user it's current.

Over two weeks I ran 433 graded agent runs (Claude Code, Codex, Gemini) on 20 libraries that changed in 2026. Most wrong choices were made at npm:

- Hedera moved its JS SDK to `@hiero-ledger/sdk`, but `@hashgraph/sdk` was still `latest`, not deprecated, and its README didn't mention the move. 6 of 6 runs built on the old package. With the old package served as deprecated through a local registry, 3 of 6 switched.
- Moss renamed its scope to `@moss-js/moss`: 3 of 6 on the new one. Deprecation alone: 4 of 6. Deprecation plus one last release of the old package whose README opens with "moved, install @moss-js/moss": 6 of 6.
- Prisma's CLI `latest` was already an 8.0 release candidate, while `@prisma/client@latest` was still 7. Three of six runs saw two majors and picked 7 on purpose, following the old rule that the two must match.
- Effect 4 kept its name and moved `latest`, so agents got the new version without trying.
- Expo had the same undeprecated trap as Hedera, yet 12 of 12 runs used the replacement. It shipped in 2025, so the models already knew it.

The npm docs don't mention that a deprecation reaches an agent only when it runs plain `npm view <pkg>`. `npm view <pkg> version` prints just the number, `npm install` prints the warning after the choice is made, and one run cut the warning off with `| tail -5`. The last release gives the agent a second place to meet the new name: the old package's README, on npm and in `node_modules`.

I now run the check below for every library on [Ready for Agents](https://readyforagents.tech) before any agent test. The full write-up, with all 20 libraries and what moved the numbers: [Coding Agents Keep Installing the Old Version of Your Library](https://dev.to/yahhi/coding-agents-keep-installing-the-old-version-of-your-library-12ef).

## Check if this applies to you
Applies if: you publish a library on npm, and in the last year you shipped a new major, renamed the package, or moved it to a new scope. `NEW` is the package you want people on, `OLD` the previous name (skip the OLD steps if the name didn't change), `FAMILY` the packages users install together (CLI, client, plugins).

Read-only steps:
1. `npm view NEW dist-tags`: note which version `latest` points to.
2. For each package in FAMILY: `npm view <pkg> dist-tags.latest`. Note the major of each.
3. `npm view OLD deprecated` (prints the message, or nothing if not deprecated) and `npm view OLD readme | head -5`: does it name NEW?
4. Ask the models without tools whether they know the new version, for example: `claude -p "From memory, no tools: do you know NEW version <N>? Give the install command and a 10-line example, or say UNKNOWN." --tools ""`. Repeat with any other agent you care about.

Has the problem: step 4 says UNKNOWN (or describes the old version), and at least one of: `latest` is not the new major (step 1), packages in FAMILY sit on different majors (step 2), OLD is not deprecated or its README doesn't name NEW (step 3).
Doesn't have it: the models already know the new version, or steps 1 to 3 are all clean.

## Reproduce this
Prerequisites: publish rights on the npm packages; the results of the check above.
Your agent will need from you: NEW, OLD, FAMILY, and your OK before anything is published.
Steps:
1. If `latest` isn't the version you want people on, move it: `npm dist-tag add NEW@<version> latest`. If a FAMILY package can't move yet, make the first line of its README say which version goes with which.
2. If the package was renamed: `npm deprecate OLD "Moved to NEW. Same API: npm install NEW"`.
3. Publish one last patch release of OLD whose README's first line says the same thing ("Moved to NEW, install NEW"), with no code changes.
Verify: `npm view OLD` shows `DEPRECATED` with the new name at the top, `npm view OLD readme | head -1` names NEW, and `npm view NEW dist-tags.latest` is the new major. For the real test, give an agent a fresh folder and "add the current <library> to this project", then check which package it installed.

Limits: 6 runs per variant, so these are big effects, not rates. The Hedera and Moss fixes were simulated through a local registry that serves the deprecation exactly as npm does; no vendor had shipped them yet when I measured.

