Umair / stalemap

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:
- **Notes:** a short, ranked list of changes written into `AGENTS.md` or `CLAUDE.md`, so the agent reads it before it starts.
- **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.
- **`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.
## Status
- **npm:** the latest release is `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.
- The project is early, and maintained by one person.
## Install
### Claude Code plugin
 [code] 
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
 [code] 
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`
 [code] 
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