Skip to content
Back to search

stalemap

MarketplaceWorks with Claude CodeGitHub

Dependency changes since your model's training cutoff, for Claude Code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/umair--stalemap/badge.svg)](/listings/umair--stalemap)

HTML

<a href="/listings/umair--stalemap"><img src="/api/listings/umair--stalemap/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code plugin

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

The plugin adds:

- a SessionStart hook that puts the notes into Claude's context for the session's model (on startup, after `/clear` and after compaction; it writes no files); - a PostToolUse hook that runs the edit-time guard after each Write or Edit; - the stalemap MCP server and two skills (`/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`.

Command line

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

The block sits between `` and ``. 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`.

Other agents: `setup --agent`

stalemap setup --agent cursor             # or codex, opencode, claude
stalemap setup --agent codex --dry-run    # print the changes, write nothing

One 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.

Any MCP client

{ "mcpServers": { "stalemap": { "command": "npx", "args": ["-y", "stalemap@latest", "mcp"] } } }

GitHub Action

- 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 dependencies

Comment 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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 12 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "stalemap",
  3. "owner": { "name": "stalemap contributors" },
  4. "description": "Dependency changes since your model's training cutoff, for Claude Code.",
  5. "plugins": [
  6. {
  7. "name": "stalemap",
  8. "source": "./plugin",
  9. "description": "Session-start notes, an MCP server and skills that tell Claude which of your dependencies changed after its training cutoff."
  10. }
  11. ]
  12. }
README.md · README · 259 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src=".github/assets/banner.svg" alt="stalemap: tell your coding agent which dependencies changed after its training cutoff" width="100%">
  3. </p>
  4. <p align="center">
  5. <a href="https://www.npmjs.com/package/stalemap"><img src="https://img.shields.io/npm/v/stalemap?color=f59e0b&label=npm" alt="npm version"></a>
  6. <a href="https://github.com/Umair/stalemap/actions/workflows/ci.yml"><img src="https://github.com/Umair/stalemap/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  7. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e" alt="MIT license"></a>
  8. <img src="https://img.shields.io/node/v/stalemap?color=64748b" alt="Node version">
  9. <a href="#claude-code-plugin"><img src="https://img.shields.io/badge/Claude_Code-plugin-d97757" alt="Claude Code plugin"></a>
  10. <a href="#any-mcp-client"><img src="https://img.shields.io/badge/MCP-server-6366f1" alt="MCP server"></a>
  11. </p>
  12. <p align="center">
  13. <a href="#install">Install</a> ·
  14. <a href="#what-the-notes-look-like">Example</a> ·
  15. <a href="#how-it-works">How it works</a> ·
  16. <a href="#results">Results</a> ·
  17. <a href="CHANGELOG.md">Changelog</a>
  18. </p>
  19. 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.
  20. stalemap finds the dependencies that changed after your model's training cutoff and tells the agent what changed, in three ways:
  21. - **Notes:** a short, ranked list of changes written into `AGENTS.md` or `CLAUDE.md`, so the agent reads it before it starts.
  22. - **Edit-time guard:** after each edit, the project's own type-check. If the code uses an API that changed after the cutoff, the agent gets the compiler error and the matching note (or the release-note or upgrade-guide section that explains it) right away. It also reports the code that still compiles but uses something that moved.
  23. - **`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.
  24. It works for JavaScript and TypeScript projects, with Claude Code, Cursor, Codex, OpenCode or any MCP client.
  25. **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](#results).
  26. <p align="center">
  27. <img src=".github/assets/how-it-works.svg" alt="Your pinned versions, what your code uses and your model's cutoff go in; stalemap diffs types, release notes and upgrade guides; your agent gets notes at session start, a guard after each edit, and search_changes on demand." width="100%">
  28. </p>
  29. ## Status
  30. - **npm:** the latest release is [`stalemap` 0.4.1](https://www.npmjs.com/package/stalemap): 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](CHANGELOG.md).
  31. - The project is early, and maintained by one person.
  32. ## Install
  33. ### Claude Code plugin
  34. ```text
  35. /plugin marketplace add Umair/stalemap
  36. /plugin install stalemap@stalemap
  37. ```
  38. The plugin adds:
  39. - a SessionStart hook that puts the notes into Claude's context for the session's model (on startup, after `/clear` and after compaction; it writes no files);
  40. - a PostToolUse hook that runs the edit-time guard after each Write or Edit;
  41. - the stalemap MCP server and two skills (`/stalemap:sync` writes the notes block; `upgrade` tells Claude to look up a package's changes before using or upgrading it).
  42. 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`.
  43. ### Command line
  44. ```bash
  45. npx stalemap # preview what changed and the block it would write
  46. npx stalemap sync # write the block into AGENTS.md or CLAUDE.md
  47. npx stalemap check # for CI: exit 1 when the block is missing or stale
  48. npx stalemap guard src/**/*.ts # run the guard by hand
  49. ```
  50. The 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`.
  51. ### Other agents: `setup --agent`
  52. ```bash
  53. stalemap setup --agent cursor # or codex, opencode, claude
  54. stalemap setup --agent codex --dry-run # print the changes, write nothing
  55. ```
  56. One 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.
  57. 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.
  58. ### Any MCP client
  59. ```json
  60. { "mcpServers": { "stalemap": { "command": "npx", "args": ["-y", "stalemap@latest", "mcp"] } } }
  61. ```
  62. ### GitHub Action
  63. ```yaml
  64. - uses: Umair/stalemap@main
  65. with:
  66. model: claude-opus-5-5 # fail CI when the notes are missing or stale
  67. # mode: comment # or comment on PRs that change dependencies
  68. ```
  69. Comment 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.
  70. ## What the notes look like
  71. <p align="center">
  72. <img src=".github/assets/terminal.svg" alt="npx stalemap on a Next.js + AI SDK app with claude-sonnet-4-5: next, ai and zod changed after the cutoff, and the notes name the changed APIs and their replacements" width="100%">
  73. </p>
  74. For a Next.js + AI SDK app and `claude-sonnet-4-5` (cutoff 2025-07-31), excerpt:
  75. ```markdown
  76. **ai** 4.3.16 → 7.0.142 (major)
  77. - `CoreMessage` was removed; use `ModelMessage`. [types]
  78. - `convertToCoreMessages` was removed; use `convertToModelMessages`. [types]
  79. - `streamText()` options no longer accept `maxTokens`, `maxSteps`, `toolCallStreaming`, … [types]
  80. **next** 15.4.0 → 16.4.2 (major)
  81. - `revalidateTag()` now requires `profile` (in `next/cache`) [types]
  82. - `NextMiddleware` is deprecated: Use `NextProxy` instead. Middleware has been renamed to Proxy. (in `next/server`) [types]
  83. ```
  84. Full output: [examples/next-ai-app.claude-sonnet-4-5.md](examples/next-ai-app.claude-sonnet-4-5.md).
  85. ## How it works
  86. 1. **Which model?** `--model`, or the model configured for Claude Code, Codex, OpenCode or Gemini CLI, or `$ANTHROPIC_MODEL`. The training cutoff comes from [models.dev](https://models.dev) (with a built-in fallback table), or pass `--cutoff YYYY-MM-DD`.
  87. 2. **What did the model know?** For each dependency, the newest stable release published at least 30 days before the cutoff (`--margin`).
  88. 3. **Which dependencies?** Direct dependencies your code imports (scanned locally), plus the ones a config file configures (`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).
  89. 4. **What changed?**
  90. - **Types:** both versions' `.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.
  91. - **Release notes:** the package's changelog or GitHub Releases, scored for breaking-change signals and for the APIs you use. A removal gets its replacement from a rename the changelog announces.
  92. - **Upgrade guides** (`--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.
  93. - **Verified examples** (`--examples`): a Before → After line under the top notes, written by Claude and kept only if it compiles against the version you pin.
  94. 5. **Fit the budget.** Notes about what your project uses come first: imported APIs, members and props, config keys it sets, file names. The default budget is 1,800 tokens (`--budget`).
  95. **The guard** runs after each edit. It runs the project's own `tsc` and reports what it finds, in this order:
  96. 1. Compile errors that come from a dependency that changed after the cutoff, with the matching note as the fix. When no note explains the error, it shows the matching section from the package's type changes, release notes or upgrade guide, found by searching with the error and the code around it.
  97. 2. Things that still type-check but changed:
  98. - config keys that moved (`experimental.ppr` in Next 16);
  99. - moved members (`HttpStatusCode.PayloadTooLarge` → `ContentTooLarge` in axios 1.20);
  100. - renamed file conventions (`middleware.ts` → `proxy.ts`);
  101. - `tsconfig.json` options the project's TypeScript rejects.
  102. 3. The compiler's other errors: in the edited file, new ones in files that import it, and a few elsewhere. These don't claim a dependency changed.
  103. 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`.
  104. **`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.
  105. **`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.
  106. Run `stalemap --help` for every command and option, including `--llm` (summaries written by Claude) and the [precomputed reports](CHANGELOG.md) for about 200 fast-moving packages (not hosted yet).
  107. ## What leaves your machine
  108. - Package names and versions go to the npm registry, GitHub (changelogs and releases; `GITHUB_TOKEN` or your `gh` login is used when available) and models.dev.
  109. - Your source code is never uploaded. The import scan is local.
  110. - With `--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.
  111. - With `probe`: the probe prompts go to the provider you choose.
  112. - With `$STALEMAP_PRECOMPUTED_URL` set: package names, not versions, go to that host.
  113. Caches live in `~/.cache/stalemap` (`$STALEMAP_CACHE` moves them).
  114. ## Results
  115. <p align="center">
  116. <img src=".github/assets/results-v4.svg" alt="Held-out v4: claude-sonnet-5-5 passed 68% with no help, 73% with a plain tsc hook, 89% with stalemap, 98% with a one-line hint; claude-sonnet-4-5 passed 46%, 53%, 64% and 78%" width="100%">
  117. </p>
  118. 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.
  119. **Held-out v4** ([protocol](bench/heldout-v4/PROTOCOL.md), [results for `claude-sonnet-5-5`](bench/heldout-v4/RESULTS-claude-sonnet-5-5.md), [for `claude-sonnet-4-5`](bench/heldout-v4/RESULTS-claude-sonnet-4-5.md)) is blind and pre-registered:
  120. - 66 tasks sampled by seed from every breaking, deprecation and behavior change that 33 popular npm packages released between July and October 2026;
  121. - 3 sessions per task, arm, mode and model;
  122. - the build frozen as `freeze/v4-final` before any v4 result existed.
  123. | setup | `claude-sonnet-5-5` | `claude-sonnet-4-5` |
  124. |---|---|---|
  125. | agent alone | 68% | 46% |
  126. | + a plain `tsc --noEmit` hook after each edit | 73% | 53% |
  127. | **+ stalemap** (notes, edit-time guard, `search_changes`) | **89%** | **64%** |
  128. | + a one-line hand-written hint naming the change (ceiling) | 98% | 78% |
  129. All four pre-registered comparisons were wins:
  130. | comparison | model | difference | interval |
  131. |---|---|---|---|
  132. | stalemap vs alone (primary) | `claude-sonnet-5-5` | +20.7 points | [13.6, 28.3] (95%) |
  133. | stalemap vs `tsc` hook | `claude-sonnet-5-5` | +16.4 points | [7.6, 26.0] (98.3%) |
  134. | stalemap vs alone | `claude-sonnet-4-5` | +17.9 points | [7.6, 28.8] (98.3%) |
  135. | stalemap vs `tsc` hook | `claude-sonnet-4-5` | +10.6 points | [0.3, 21.7] (98.3%) |
  136. - **One-shot is where it matters most:** on `claude-sonnet-5-5`, 89% vs 60% with no help. With checks, it's 89% vs 77%.
  137. - **Fewer stale edits:** the agent's first edit used a stale API in 11% of `claude-sonnet-5-5` sessions with stalemap, vs 27% with no help.
  138. - **Cost:**
  139. - `claude-sonnet-5-5`: median $0.050 vs $0.041 per session with no help, with about the same turns (7 vs 8).
  140. - `claude-sonnet-4-5`: higher, at $0.124 vs $0.085 and 79 s vs 47 s.
  141. - **A current model still needs it.** Even `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.
  142. - Results against third-party tools aren't published.
  143. **Earlier suites** (all `claude-sonnet-4-5`):
  144. - [Held-out v1](bench/heldout/RESULTS.md) (pre-registered, 10 tasks): 83% vs 50% alone, a win.
  145. - [Held-out v2](bench/heldout-v2/RESULTS.md) (blind, 10 tasks): 35% vs 23% alone, a tie.
  146. - [Held-out v3](bench/heldout-v3/RESULTS.md) (blind, 59 tasks): 53% vs 43% alone, a win. It tied a plain `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.
  147. **What to keep in mind:**
  148. - **Same author.** stalemap, the harness and the protocols have one author. The v4 tasks were written by a separate session that never saw stalemap's code, notes or results. An independent, equally blind reviewer checked them and applied the pilot rule. The tasks, hidden tests, sampling files, review, pilot and per-session results are in `bench/` for you to check.
  149. - **JavaScript and TypeScript, two Claude models.** Other agents and models weren't measured.
  150. - **Pre-registered vs post-hoc.** Only the comparisons fixed in a protocol before a run are claims. The changes made after v3 were post-hoc, which is why v4 was needed.
  151. ## Limits
  152. - JavaScript and TypeScript only, and one `package.json` (no workspace traversal yet).
  153. - Packages without bundled types get release-note notes only (`@types/*` aren't diffed).
  154. - Usage tracking stops at imported names and `x.member` accesses; instance chains like `client.messages.create({ temperature })` aren't traced.
  155. - Behavior changes that never reach a type signature come only from release notes and (with `--guides`) upgrade guides. If neither names the setting, stalemap can't either.
  156. - Ranking release notes is heuristic and noisy for prose-heavy changelogs.
  157. - Agents sometimes ignore correct notes. The guard catches what fails to compile and some of what still compiles (moved keys and members, renamed files); other stale code that still compiles is caught only if a note covers it.
  158. ## Run the benchmark
  159. The harness, the tasks, the protocols and the results are in [`bench/`](bench/README.md). In short:
  160. ```bash
  161. npm install && npm run build
  162. mkdir -p bench/.work/template-heldout-v4-latest && cp bench/heldout-v4/templates/latest/*.json bench/.work/template-heldout-v4-latest/
  163. (cd bench/.work/template-heldout-v4-latest && npm install --ignore-scripts)
  164. npx tsx bench/heldout-v4/validate.ts # reference solutions pass, stale versions fail
  165. npx tsx bench/run.ts --suite heldout-v4 --model claude-sonnet-5-5 --arms alone,stalemap-full,tsc-hook,oracle --examples --guides --reps 3
  166. npx tsx bench/analyze.ts bench/results/<dir>
  167. ```
  168. 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](bench/README.md) for the arms, isolation, sharding and costs.
  169. ## Development
  170. ```bash
  171. git clone https://github.com/Umair/stalemap && cd stalemap
  172. npm install
  173. npm run build # → dist/cli.js
  174. npm test # node:test via tsx
  175. node dist/cli.js scan --cwd test/fixtures/next-ai-app --model claude-sonnet-4-5
  176. npm link # optional: put your local build on your PATH
  177. ```
  178. Library use:
  179. ```ts
  180. import { runStalemap, packageChanges, checkBlock } from "stalemap";
  181. const { rendered } = await runStalemap({ cwd: ".", model: "claude-opus-5-5" });
  182. ```
  183. ## Contributing
  184. Bug reports, false or missing notes, and new benchmark tasks are all welcome. See [CONTRIBUTING.md](CONTRIBUTING.md). To report a security problem, see [SECURITY.md](SECURITY.md).
  185. ## License
  186. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.