What is stalemap?
stalemap finds the npm dependencies in a project whose APIs changed after the model's training cutoff and passes those changes to the coding agent. It works out the cutoff from the configured model through models.dev, takes the newest stable release from at least 30 days before it as what the model knows, and compares that with the version you pin.
The comparison downloads both versions' .d.ts type files and diffs them with the TypeScript compiler API, then adds breaking-change items from changelogs and GitHub Releases. The agent gets the result three ways: a ranked notes block in AGENTS.md or CLAUDE.md (1,800 tokens by default), a guard that runs the project's own tsc after each edit and attaches the matching note to any error, and a search_changes MCP tool.
It ships as an npm package, a Claude Code plugin, a GitHub Action and setup commands for Cursor, Codex and OpenCode. The code is MIT, the repository was created on 19 October 2026 and the latest release is 0.4.1 from 20 October.
Is stalemap worth it?
stalemap targets a specific failure: an agent writes code for the version of a library it was trained on, not the one you pin. The README's examples are maxSteps against AI SDK 7, required_error against zod 4 and middleware.ts against Next 16. Instead of fetching whole documentation pages, it diffs the type definitions of the two versions and hands the agent only what changed in the APIs your code imports.
The evidence is better than most agent tooling offers. In a blind, pre-registered test of 66 tasks drawn from changes 33 popular npm packages shipped between July and October 2026, claude-sonnet-5-5 passed 89% of sessions with stalemap against 68% alone and 73% with a plain tsc --noEmit hook after each edit; the interval for the main comparison was 13.6 to 28.3 points. The author also reports the ceiling: a one-line hand-written hint naming the change reached 98%. The tool, harness and protocols share one author, though the tasks were written by a separate session and checked by an independent reviewer, and only two Claude models were measured.
It is not free to run. Median session cost on claude-sonnet-5-5 rose from $0.041 to $0.050, and on claude-sonnet-4-5 from $0.085 to $0.124 with sessions taking 79 seconds instead of 47. Code never leaves the machine, but package names and versions go to the npm registry, GitHub and models.dev, and the optional --llm, --examples and --guides modes send type diffs and the names of imported APIs to Claude.
The limits are stated plainly in the README: one package.json with no workspace support, no diffing of @types packages, usage tracking that stops at imported names and x.member accesses, and setup for Cursor, Codex and OpenCode that has not been tried in a real install. Context7 covers more languages by serving current documentation on request; stalemap is the stricter tool, because the edit-time guard catches stale calls even when the agent never thinks to ask.
Where it earns its place
A solo developer on a Next.js 16 and AI SDK 7 app using Claude Code
Stop the agent writing middleware.ts and maxSteps code that no longer compiles
Install the Claude Code plugin with two /plugin commands; notes load at session start and the guard reports compile errors with the fix after each edit. Expect sessions to cost a little more, about $0.009 a task at the median on claude-sonnet-5-5.
A tech lead at a 20-developer TypeScript agency
Keep agent instructions current when Renovate bumps a major version
Commit the notes block, then add the GitHub Action with a model input: npx stalemap check fails CI when the block is stale, or comment mode posts what changed on pull requests that touch dependencies. Comment mode needs pull-requests: write.
A developer using Cursor or Codex instead of Claude Code
Give the agent current API changes on demand while it works
Run stalemap setup --agent cursor (or codex) to write the notes, register the MCP server and install the post-edit guard as project files. The author says this path has not been tried in a real Cursor or Codex install yet.
Before you commit
- Setup
- /plugin marketplace add Umair/stalemap then /plugin install stalemap@stalemap in Claude Code, or npx stalemap to preview and npx stalemap sync to write the block; any MCP client can run npx -y stalemap@latest mcp.
- Integrations
- Four MCP tools (search_changes, package_changes, project_changes, check_notes); Claude Code SessionStart and PostToolUse hooks; setup for Cursor, Codex and OpenCode; a GitHub Action; npm, pnpm, yarn and bun lockfiles.
- Data and privacy
- Source code is scanned locally and never uploaded. Package names and versions go to the npm registry, GitHub and models.dev; --llm, --examples and --guides send type diffs, release-note excerpts and imported API names to Claude. Caches live in ~/.cache/stalemap. MIT.
- Cost at scale
- The tool is free. In the author's benchmark it raised median cost per session from $0.041 to $0.050 on claude-sonnet-5-5 and from $0.085 to $0.124 on claude-sonnet-4-5; optional Claude-written summaries add API calls on your key.
- Limits
- JavaScript and TypeScript only; one package.json; @types packages not diffed; behaviour changes are caught only if release notes or upgrade guides name them; agents sometimes ignore correct notes.
What’s good
- Diffs real type definitions, not a model's summary of docs
- Edit-time guard pairs each compiler error with the matching change note
- Blind, pre-registered benchmark with the ceiling and costs reported
- Source code is never uploaded; scan is local
- Claude Code plugin, MCP server, CLI and GitHub Action
What’s not
- JavaScript and TypeScript only; one package.json, no workspaces
- Raises median session cost, about 22% on claude-sonnet-5-5
- Cursor, Codex and OpenCode setup untested in real installs
- One maintainer; created 19 October 2026
Best for
TypeScript developers whose coding agent keeps writing code for older versions of fast-moving packages such as Next.js, the AI SDK or zod.
stalemap: common questions
- Is stalemap worth it?
- A narrow fix for a real and costly problem, with an unusually careful benchmark behind it, but only for JavaScript and TypeScript and only from one maintainer. We rate it 3.8 out of 5.
- How much does stalemap cost?
- Free under MIT. Optional --llm, --examples and --guides features call Claude on your own Anthropic key or Claude Code login.
- What are the downsides of stalemap?
- JavaScript and TypeScript only; one package.json, no workspaces; raises median session cost, about 22% on claude-sonnet-5-5; cursor, Codex and OpenCode setup untested in real installs; one maintainer; created 19 October 2026.
- Who is stalemap best for?
- TypeScript developers whose coding agent keeps writing code for older versions of fast-moving packages such as Next.js, the AI SDK or zod.
- How much does stalemap cost for a team or in production?
- The tool is free. In the author's benchmark it raised median cost per session from $0.041 to $0.050 on claude-sonnet-5-5 and from $0.085 to $0.124 on claude-sonnet-4-5; optional Claude-written summaries add API calls on your key.
- Is stalemap safe for company data?
- Source code is scanned locally and never uploaded. Package names and versions go to the npm registry, GitHub and models.dev; --llm, --examples and --guides send type diffs, release-note excerpts and imported API names to Claude. Caches live in ~/.cache/stalemap. MIT.
Answers checked Nov 5, 2026.