When Claude uses the old version

What it is and why it matters

You ask Claude for a new feature, it writes it with full confidence, and the app no longer starts. You read the error and find it used an option that no longer exists in the installed version of the library, or a file with its old name. The code looked right. And it was right, for the library as it was a few months ago.

That's what stalemap is for. It looks at the versions of your project's libraries, finds what changed after the date Claude's training stops, and gives Claude a short list before it starts. Then, after every edit, it checks the code: if Claude used something outdated, it tells Claude what to use now.

It's for anyone building a JavaScript or TypeScript app with Claude Code, on libraries that change often. One thing up front: it's not made by Anthropic. It's an open-source community project under the MIT license, started on 19 October 2026. It's young and maintained by one person: treat it as extra help, not a guarantee.

1. Why Claude writes outdated code

A model like Claude learns from a mountain of text and code collected up to a certain date. That date is called the training cutoff. Whatever happens after it, Claude doesn't know.

Libraries, on the other hand, keep moving. The latest version comes out, an option disappears, a function gets renamed, a file gets a new name. Claude doesn't know, so it uses the names it saw a thousand times while training. The stalemap README gives three examples:

• maxSteps, an option of streamText in the AI SDK, which newer versions no longer accept.
• required_error, a zod option that newer versions changed.
• middleware.ts in Next.js, which is called proxy.ts in newer versions.

stalemap does a simple calculation. It reads which model you're using and finds its cutoff date. For each library your code imports, it estimates which version the model knew: the newest one released at least 30 days before that date. Then it compares it with the version you actually installed, looking at the library's types and its release notes, the list of changes its maintainers publish. Whatever changed in between becomes a note.

2. Install it in Claude Code

You need Node.js 20 or later and a JavaScript or TypeScript project with a package.json. Then, inside a Claude Code session, type two commands:

/plugin marketplace add Umair/stalemap
/plugin install stalemap@stalemap

1. The first adds the stalemap marketplace, the catalog Claude Code gets the plugin from. You only do this once.
2. The second doesn't install right away: it opens the /plugin panel on the plugin's details, where you choose where to turn it on, for example just for you or for the whole project.
3. Before you confirm, read the details. A plugin can run commands and an MCP server on your computer: you should know what you're installing.
4. To turn it off or remove it later, open /plugin and go to the Installed tab.

The plugin adds two hooks, commands Claude Code runs on its own at a set moment: one at the start of a session and one after every edit. It also adds an MCP server, which Claude can use to look up a library's changes in its own words, and two skills. Let's go through them one at a time.

3. What Claude sees at the start of a session

When you open a session, stalemap puts the notes about changed libraries into Claude's context, worked out for that session's model. It does it again after /clear and after compaction, when Claude Code summarizes a long conversation. It writes no files: the notes live only in the session.

The notes are a short, ranked list. First come the changes that touch what your project actually uses: the functions you import, the config options, the file names. Each note says what was removed or renamed and what to use instead.

If you want the notes in CLAUDE.md

With the /stalemap:sync skill, the notes also go into CLAUDE.md or AGENTS.md, the file with your project's rules. That way they stay in the repository and the people working with you see them too. The block sits between two markers, <!-- stalemap:start --> and <!-- stalemap:end -->, and the rest of the file is left alone.

One detail: Claude Code reads CLAUDE.md, not AGENTS.md. If your notes live in AGENTS.md, add the line @AGENTS.md to CLAUDE.md.

4. The check after every edit

Every time Claude writes or edits a file, the second hook runs: the guard. It runs your project's own type check, tsc, the TypeScript compiler, and reports what it finds back to Claude, in this order:

1. Errors that come from a library that changed after the cutoff, with the note that says how to fix them.
2. Things that still compile but have changed: moved config keys and members, renamed files, like middleware.ts becoming proxy.ts.
3. The compiler's other errors, in the edited file and in the files that use it. These don't claim a library changed: they're ordinary errors.

So Claude sees the error and the fix right away, while it works, instead of you finding out when you open the app. One limit to know: the guard only catches part of the outdated code that still compiles. The rest it catches only if a note covers it.

Before you upgrade a library

The plugin also has a skill, upgrade, that tells Claude to look up a package's changes before using or upgrading it. This is how I ask:

I want to upgrade [library name] to the latest version. Before you touch the code, use stalemap to look up what changed in this library: removed or renamed functions, new required options, files with a new name.
Then give me a list of the places in my project that need to change, with the file name for each.
Don't change anything until I say ok.

And once the upgrade is done:

I've upgraded [library name]. Run the type check and the tests, and tell me what broke and why. Fix one thing at a time.

5. From the terminal and in automated checks

You can also use stalemap without the plugin, from the terminal, in the project folder:

• npx stalemap: a preview. It shows what changed and the block it would write.
• npx stalemap sync: writes the block into CLAUDE.md or AGENTS.md.
• npx stalemap check: checks that the block is there and up to date.

check is meant for CI, the automated checks that run on every push, for example with GitHub Actions. If the block is missing or out of date, it exits with an error and the check fails. So if someone upgrades a library and forgets the notes, you find out right away. The README also has a ready-made GitHub Action.

Keep in mind that the notes take up room in Claude's context, which means extra tokens every session. By default stalemap keeps them within about 1,800 tokens and puts the ones about the code you use first.

6. What leaves your computer

It's the part I'd check first, so here it is, plainly. In basic use:

• Your code never leaves. It works out which libraries you import on your own computer.
• Only package names and versions go out: to the npm registry, to GitHub for the release notes, and to models.dev for the models' cutoff dates.
• No API key is needed, and stalemap has no server of its own and collects no telemetry.

Then there are three options, --llm, --guides and --examples, which have Claude write summaries, notes from upgrade guides and before-and-after examples. With those, Claude receives the type diffs, excerpts of the release notes and the names of the functions you import. Not your code. But they use tokens: turn them on when you need them, not by habit.

Common mistakes

• Installing it on a Flutter, Python or Swift project. It only works with JavaScript and TypeScript.
• Confirming the install without reading the plugin's details. It runs commands on your computer: check what it does first.
• Thinking it replaces your tests. The notes help, but Claude sometimes ignores them. Tests and the type check are still your safety net.
• Using it in a monorepo with several package.json files. For now it reads only one, without workspaces.
• Turning on --llm, --guides or --examples on every run. They send data to Claude and use tokens.

Checklist

• The project is JavaScript or TypeScript, with a single package.json
• I have Node.js 20 or later
• I read the plugin's details before installing it
• I ran the two commands in Claude Code
• I looked at the notes with npx stalemap
• If I want the notes in the repository, I ran /stalemap:sync
• My CI runs npx stalemap check
• I only use --llm, --guides and --examples when I need them

Frequently asked questions