
Tell your coding agent which dependencies changed after its training cutoff. Diffs types and
Tell your coding agent which dependencies changed after its training cutoff. Diffs types and changelogs, writes a short block into AGENTS.md / CLAUDE.md.
·
Install · Example · How it works · Results · Changelog
Coding agents learn libraries from training data that stops at a cutoff date. When your project pins newer versions, the agent writes code for the old API: maxSteps against AI SDK 7, required_error against zod 4, middleware.ts against Next 16.
stalemap finds the dependencies that changed after your model's training cutoff and tells the agent what changed, in three ways:
AGENTS.md or CLAUDE.md, so the agent reads it before it starts.search_changes: an MCP tool the agent can ask in its own words, such as "resolve alias in next.config", to get the matching changes with their sources.It works for JavaScript and TypeScript projects, with Claude Code, Cursor, Codex, OpenCode or any MCP client.
In a blind, pre-registered benchmark of 66 tasks built from changes released after June 2026, claude-sonnet-5-5 agents passed 89% of sessions with stalemap, against 68% with no help and 73% with a plain tsc --noEmit hook after each edit. See Results.
stalemap 0.4.1: the build tested in held-out v4 (0.4.0), plus a one-line footer in the notes block. npx stalemap, the Claude Code plugin and the GitHub Action all run it. See the changelog./plugin marketplace add Umair/stalemap
/plugin install stalemap@stalemapThe plugin adds:
/clear and after compaction; it writes no files);/stalemap:sync writes the notes block; upgrade tells Claude to look up a package's changes before using or upgrading it).The hooks and the MCP server run npx -y stalemap@latest, so they use the latest npm release. Its MCP tools are search_changes, package_changes, project_changes and check_notes.
npx stalemap # preview what changed and the block it would write
npx stalemap sync # write the block into AGENTS.md or CLAUDE.md
npx stalemap check # for CI: exit 1 when the block is missing or stale
npx stalemap guard src/**/*.ts # run the guard by handThe block sits between <!-- stalemap:start --> and <!-- stalemap:end -->. Text outside it is never touched. Claude Code reads CLAUDE.md; if your notes live in AGENTS.md, add @AGENTS.md to CLAUDE.md or pass --target CLAUDE.md.
setup --agentstalemap setup --agent cursor # or codex, opencode, claude
stalemap setup --agent codex --dry-run # print the changes, write nothingOne command per agent writes the notes, registers the MCP server and installs the guard as the agent's post-edit hook, as project files you can commit. It merges into existing config files, keeps entries it didn't write, and re-running it changes nothing.
One caveat: it hasn't been tried in a real Cursor, Codex or OpenCode install yet. Cursor doesn't pass a postToolUse hook's context to the model yet, so setup adds a stop-hook fallback that sends unreported findings as a follow-up message.
{ "mcpServers": { "stalemap": { "command": "npx", "args": ["-y", "stalemap@latest", "mcp"] } } }- uses: Umair/stalemap@main
with:
model: claude-opus-5-5 # fail CI when the notes are missing or stale
# mode: comment # or comment on PRs that change dependenciesComment mode needs permissions: pull-requests: write. It lists each changed dependency (what the model knows → what's pinned) with its notes, and updates the comment on later pushes.
For a Next.js + AI SDK app and claude-sonnet-4-5 (cutoff 2025-07-31), excerpt:
**ai** 4.3.16 → 7.0.142 (major)
- `CoreMessage` was removed; use `ModelMessage`. [types]
- `convertToCoreMessages` was removed; use `convertToModelMessages`. [types]
- `streamText()` options no longer accept `maxTokens`, `maxSteps`, `toolCallStreaming`, … [types]
**next** 15.4.0 → 16.4.2 (major)
- `revalidateTag()` now requires `profile` (in `next/cache`) [types]
- `NextMiddleware` is deprecated: Use `NextProxy` instead. Middleware has been renamed to Proxy. (in `next/server`) [types]Full output: examples/next-ai-app.claude-sonnet-4-5.md.
--model, or the model configured for Claude Code, Codex, OpenCode or Gemini CLI, or $ANTHROPIC_MODEL. The training cutoff comes from models.dev (with a built-in fallback table), or pass --cutoff YYYY-MM-DD.--margin).tsconfig.json, next.config.*, the Prisma schema, Vitest and ESLint configs, and others). --all checks every direct dependency. Pinned versions come from node_modules or the lockfile (npm, pnpm, yarn, bun)..d.ts files are downloaded and compared with the TypeScript compiler API: removed, renamed and moved exports, new required parameters, removed or newly required options, and new @deprecated tags with their hints.--guides): for changes that never reach a type signature, like a new default or a renamed file convention. Claude turns each guide into short notes, and a note is kept only if it quotes the guide.--examples): a Before → After line under the top notes, written by Claude and kept only if it compiles against the version you pin.--budget).The guard runs after each edit. It runs the project's own tsc and reports what it finds, in this order:
experimental.ppr in Next 16);HttpStatusCode.PayloadTooLarge → ContentTooLarge in axios 1.20);middleware.ts → proxy.ts);tsconfig.json options the project's TypeScript rejects.So a plain type-check hook is a subset of the guard. STALEMAP_GUARD_TSC=0 limits the guard to dependency changes. Deprecations are reported only with STALEMAP_GUARD_DEPRECATIONS=1.
search_changes (also stalemap search <query>) searches everything stalemap found for the project's dependencies: every type change, every release-note item, cached upgrade-guide notes and, for a new major, the guides' text. Ranking is BM25 over words and split identifiers (resolveAlias matches "resolve alias"), weighted toward what the project uses. The first search builds an index from the analysis caches; later ones are offline and fast.
stalemap probe measures which notes a model actually needs: it asks the model to write code for each change, type-checks the answers against the pinned version, and runs again with the notes. Notes the model already gets right are dropped from the block. Probe tasks name the old API, so they measure whether the model knows a change when pointed at it, which is easier than noticing it unprompted.
Run stalemap --help for every command and option, including --llm (summaries written by Claude) and the precomputed reports for about 200 fast-moving packages (not hosted yet).
GITHUB_TOKEN or your gh login is used when available) and models.dev.--llm, --examples or --guides: type diffs, release-note excerpts, guide text and the names of APIs you import go to Claude (the Anthropic API or claude -p). Your code isn't included.probe: the probe prompts go to the provider you choose.$STALEMAP_PRECOMPUTED_URL set: package names, not versions, go to that host.Caches live in ~/.cache/stalemap ($STALEMAP_CACHE moves them).
Every result comes from headless Claude Code sessions graded by hidden tests the agent never sees. Each task is run in two modes: one-shot (file tools only) and checks (the agent can also run npm test and tsc). Intervals come from a two-level bootstrap (tasks, then runs). A difference counts as a win only when its interval excludes zero.
Held-out v4 (protocol, results for claude-sonnet-5-5, for claude-sonnet-4-5) is blind and pre-registered:
freeze/v4-final before any v4 result existed.| setup | claude-sonnet-5-5 | claude-sonnet-4-5 |
|---|---|---|
| agent alone | 68% | 46% |
+ a plain tsc --noEmit hook after each edit | 73% | 53% |
+ stalemap (notes, edit-time guard, search_changes) | 89% | 64% |
| + a one-line hand-written hint naming the change (ceiling) | 98% | 78% |
All four pre-registered comparisons were wins:
| comparison | model | difference | interval |
|---|---|---|---|
| stalemap vs alone (primary) | claude-sonnet-5-5 | +20.7 points | [13.6, 28.3] (95%) |
stalemap vs tsc hook | claude-sonnet-5-5 | +16.4 points | [7.6, 26.0] (98.3%) |
| stalemap vs alone | claude-sonnet-4-5 | +17.9 points | [7.6, 28.8] (98.3%) |
stalemap vs tsc hook | claude-sonnet-4-5 | +10.6 points | [0.3, 21.7] (98.3%) |
claude-sonnet-5-5, 89% vs 60% with no help. With checks, it's 89% vs 77%.claude-sonnet-5-5 sessions with stalemap, vs 27% with no help.claude-sonnet-5-5: median $0.050 vs $0.041 per session with no help, with about the same turns (7 vs 8).claude-sonnet-4-5: higher, at $0.124 vs $0.085 and 79 s vs 47 s.claude-sonnet-5-5 failed a third of these tasks on its own, and a one-line hint fixed almost all of them. stalemap closes about two-thirds of that gap.Earlier suites (all claude-sonnet-4-5):
tsc hook. The changes in 0.3 and 0.4 came from what v3's transcripts showed: the guard didn't run the project's own TypeScript, notes and search lost the fix text, and search wasn't used enough. v4 is the first blind test of those changes.What to keep in mind:
bench/ for you to check.package.json (no workspace traversal yet).@types/* aren't diffed).x.member accesses; instance chains like client.messages.create({ temperature }) aren't traced.--guides) upgrade guides. If neither names the setting, stalemap can't either.The harness, the tasks, the protocols and the results are in bench/. In short:
npm install && npm run build
mkdir -p bench/.work/template-heldout-v4-latest && cp bench/heldout-v4/templates/latest/*.json bench/.work/template-heldout-v4-latest/
(cd bench/.work/template-heldout-v4-latest && npm install --ignore-scripts)
npx tsx bench/heldout-v4/validate.ts # reference solutions pass, stale versions fail
npx tsx bench/run.ts --suite heldout-v4 --model claude-sonnet-5-5 --arms alone,stalemap-full,tsc-hook,oracle --examples --guides --reps 3
npx tsx bench/analyze.ts bench/results/<dir>Sessions run on whatever Claude Code is signed in with, and a full v4 run is about 1,600 sessions per model, so start with --reps 1 or --tasks. Transcripts go to bench/results/<dir>/runs/, which is git-ignored. See bench/README.md for the arms, isolation, sharding and costs.
git clone https://github.com/Umair/stalemap && cd stalemap
npm install
npm run build # → dist/cli.js
npm test # node:test via tsx
node dist/cli.js scan --cwd test/fixtures/next-ai-app --model claude-sonnet-4-5
npm link # optional: put your local build on your PATHLibrary use:
import { runStalemap, packageChanges, checkBlock } from "stalemap";
const { rendered } = await runStalemap({ cwd: ".", model: "claude-opus-5-5" });Bug reports, false or missing notes, and new benchmark tasks are all welcome. See CONTRIBUTING.md. To report a security problem, see SECURITY.md.
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add stalemap -- npx -y stalemap@latest mcp{
"mcpServers": {
"stalemap": {
"args": [
"-y",
"stalemap@latest",
"mcp"
],
"command": "npx"
}
}
}code --add-mcp '{"name":"stalemap","args":["-y","stalemap@latest","mcp"],"command":"npx"}'[mcp_servers.stalemap]
command = "npx"
args = ["-y", "stalemap@latest", "mcp"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/stalemap to learn what the "Stalemap" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
npx stalemap # preview what changed and the block it would write
npx stalemap sync # write the block into AGENTS.md or CLAUDE.md
npx stalemap check # for CI: exit 1 when the block is missing or stale
npx stalemap guard src/**/*.ts # run the guard by hand
npx tsx bench/heldout-v4/validate.ts # reference solutions pass, stale versions fail
npx tsx bench/run.ts --suite heldout-v4 --model claude-sonnet-5-5 --arms alone,stalemap-full,tsc-hook,oracle --examples --guides --reps 3| Name | What it does |
|---|---|
search_changes | Searches what changed in this project's dependencies since your training data, for the versions it has installed: removed, renamed and moved APIs, options and config keys, new required arguments, chan |
package_changes | Before writing or changing code that calls a third-party npm package, call this to learn which of its APIs changed after your training cutoff: removed or renamed exports, new required parameters, remo |
project_changes | Scan a JavaScript/TypeScript project and list the dependencies it imports that changed after your training cutoff, with the specific API changes that affect this code. Use it at the start of a task in |
check_notes | Check whether the project's stalemap notes block is missing or out of date for the current dependencies and model. Offline and fast. |
Read live from the server on October 28, 2026.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/stalemap)Nothing comparable is listed yet.
v0.4.1stalemap 0.4.1Release notesv0.4.0stalemap 0.4.0Release notesv0.3.1stalemap 0.3.1Release notesv0.3.0stalemap 0.3.0Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "stalemap" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.