O que é stalemap?
O stalemap encontra as dependências npm de um projeto cujas APIs mudaram depois da data de corte do treinamento do modelo e repassa essas mudanças ao agente de código. Ele descobre a data de corte do modelo configurado pelo models.dev, considera como conhecida pelo modelo a versão estável mais recente publicada pelo menos 30 dias antes, e compara com a versão que você fixou.
Para comparar, baixa os arquivos de tipos .d.ts das duas versões e os confronta com a API do compilador do TypeScript, e acrescenta mudanças incompatíveis tiradas de changelogs e GitHub Releases. O agente recebe o resultado de três formas: um bloco de notas ordenado em AGENTS.md ou CLAUDE.md (1.800 tokens por padrão), uma guarda que roda o tsc do próprio projeto depois de cada edição e anexa a nota correspondente a cada erro, e uma ferramenta MCP chamada search_changes.
É distribuído como pacote npm, plugin do Claude Code, GitHub Action e comandos de configuração para Cursor, Codex e OpenCode. O código é MIT, o repositório foi criado em 19 de outubro de 2026 e a versão mais recente é a 0.4.1, de 20 de outubro.
stalemap vale a pena?
O stalemap mira uma falha específica: o agente escreve código para a versão da biblioteca com que foi treinado, não para a que você fixou. Os exemplos do README são maxSteps contra o AI SDK 7, required_error contra o zod 4 e middleware.ts contra o Next 16. Em vez de buscar páginas inteiras de documentação, ele compara as definições de tipos das duas versões e passa ao agente só o que mudou nas APIs que o seu código importa.
As evidências são melhores que as da maioria das ferramentas para agentes. Em um teste cego e pré-registrado com 66 tarefas tiradas de mudanças que 33 pacotes npm populares lançaram entre julho e outubro de 2026, o claude-sonnet-5-5 passou em 89% das sessões com stalemap, contra 68% sozinho e 73% com um simples hook de tsc --noEmit depois de cada edição; o intervalo da comparação principal foi de 13,6 a 28,3 pontos. O autor também informa o teto: uma dica de uma linha escrita à mão nomeando a mudança chegou a 98%. A ferramenta, o ambiente de teste e os protocolos têm o mesmo autor, mas as tarefas foram escritas por uma sessão separada e conferidas por um revisor independente, e só dois modelos Claude foram medidos.
Usar não sai de graça. O custo mediano por sessão subiu de $0.041 para $0.050 no claude-sonnet-5-5 e de $0.085 para $0.124 no claude-sonnet-4-5, com sessões de 79 segundos em vez de 47. O código nunca sai da máquina, mas nomes e versões de pacotes vão para o registro do npm, o GitHub e o models.dev, e os modos opcionais --llm, --examples e --guides enviam ao Claude diffs de tipos e os nomes das APIs importadas.
Os limites estão claros no README: um único package.json sem suporte a workspaces, sem comparação de pacotes @types, rastreamento de uso que para em nomes importados e acessos x.member, e uma configuração para Cursor, Codex e OpenCode que ainda não foi testada em uma instalação real. O Context7 cobre mais linguagens servindo documentação atual sob demanda; o stalemap é a ferramenta mais rigorosa, porque a guarda pega chamadas desatualizadas na edição mesmo quando o agente nem pensa em perguntar.
Onde ele se destaca
Um desenvolvedor solo com um app em Next.js 16 e AI SDK 7 usando Claude Code
Fazer o agente parar de escrever código com middleware.ts e maxSteps que não compila mais
Instalar o plugin do Claude Code com dois comandos /plugin; as notas carregam no início da sessão e a guarda relata erros de compilação com a correção depois de cada edição. As sessões ficam um pouco mais caras, cerca de $0.009 por tarefa na mediana com claude-sonnet-5-5.
Um tech lead em uma agência de TypeScript com 20 desenvolvedores
Manter as instruções dos agentes em dia quando o Renovate sobe uma versão major
Fazer commit do bloco de notas e adicionar a GitHub Action com o parâmetro model: npx stalemap check falha o CI quando o bloco está desatualizado, ou o modo comentário publica o que mudou nos pull requests que mexem em dependências. O modo comentário precisa de pull-requests: write.
Uma desenvolvedora que usa Cursor ou Codex em vez de Claude Code
Dar ao agente as mudanças de API atuais sob demanda enquanto ele trabalha
Rodar stalemap setup --agent cursor (ou codex) para escrever as notas, registrar o servidor MCP e instalar a guarda pós-edição como arquivos do projeto. Segundo o autor, esse caminho ainda não foi testado em uma instalação real de Cursor ou Codex.
Antes de decidir
- Configuração
- /plugin marketplace add Umair/stalemap e depois /plugin install stalemap@stalemap no Claude Code, ou npx stalemap para a prévia e npx stalemap sync para escrever o bloco; qualquer cliente MCP pode rodar npx -y stalemap@latest mcp.
- Integrações
- Quatro ferramentas MCP (search_changes, package_changes, project_changes, check_notes); hooks SessionStart e PostToolUse do Claude Code; configuração para Cursor, Codex e OpenCode; uma GitHub Action; lockfiles de npm, pnpm, yarn e bun.
- Dados e privacidade
- O código-fonte é analisado localmente e nunca enviado. Nomes e versões de pacotes vão para o registro do npm, o GitHub e o models.dev; --llm, --examples e --guides enviam ao Claude diffs de tipos, trechos de notas de versão e nomes de APIs importadas. Os caches ficam em ~/.cache/stalemap. MIT.
- Custo em escala
- A ferramenta é gratuita. No benchmark do autor, ela elevou o custo mediano por sessão de $0.041 para $0.050 no claude-sonnet-5-5 e de $0.085 para $0.124 no claude-sonnet-4-5; resumos opcionais escritos pelo Claude somam chamadas de API na sua chave.
- Limites
- Só JavaScript e TypeScript; um package.json; pacotes @types não são comparados; mudanças de comportamento só são detectadas se notas de versão ou guias de atualização as citarem; às vezes os agentes ignoram notas corretas.
O que é bom
- Compara definições de tipos reais, não um resumo de documentação feito por modelo
- A guarda na edição junta cada erro do compilador à nota de mudança certa
- Benchmark cego e pré-registrado, com teto e custos publicados
- O código-fonte nunca é enviado; a análise é local
- Plugin do Claude Code, servidor MCP, CLI e GitHub Action
O que não é
- Só JavaScript e TypeScript; um package.json, sem workspaces
- Aumenta o custo mediano por sessão, cerca de 22% no claude-sonnet-5-5
- Configuração para Cursor, Codex e OpenCode não testada em instalações reais
- Um só mantenedor; criado em 19 de outubro de 2026
Ideal para
Desenvolvedores TypeScript cujo agente de código continua escrevendo para versões antigas de pacotes que mudam rápido, como Next.js, o AI SDK ou zod.
stalemap: perguntas frequentes
- stalemap vale a pena?
- Uma solução estreita para um problema real e caro, com um benchmark incomumente cuidadoso por trás, mas só para JavaScript e TypeScript e de um único mantenedor. Damos nota 3.8 de 5.
- Quanto custa stalemap?
- Gratuito sob MIT. Os recursos opcionais --llm, --examples e --guides chamam o Claude com a sua própria chave da Anthropic ou o seu login do Claude Code.
- Quais são as desvantagens de stalemap?
- Só JavaScript e TypeScript; um package.json, sem workspaces; aumenta o custo mediano por sessão, cerca de 22% no claude-sonnet-5-5; configuração para Cursor, Codex e OpenCode não testada em instalações reais; um só mantenedor; criado em 19 de outubro de 2026.
- Para quem stalemap é indicado?
- Desenvolvedores TypeScript cujo agente de código continua escrevendo para versões antigas de pacotes que mudam rápido, como Next.js, o AI SDK ou zod.
- Quanto custa stalemap para uma equipe ou em produção?
- A ferramenta é gratuita. No benchmark do autor, ela elevou o custo mediano por sessão de $0.041 para $0.050 no claude-sonnet-5-5 e de $0.085 para $0.124 no claude-sonnet-4-5; resumos opcionais escritos pelo Claude somam chamadas de API na sua chave.
- stalemap é seguro para dados da empresa?
- O código-fonte é analisado localmente e nunca enviado. Nomes e versões de pacotes vão para o registro do npm, o GitHub e o models.dev; --llm, --examples e --guides enviam ao Claude diffs de tipos, trechos de notas de versão e nomes de APIs importadas. Os caches ficam em ~/.cache/stalemap. MIT.
Respostas verificadas em 5 de nov. de 2026.