sota-anchor

sota-anchor

Seu agente de codificação não sabe o que foi lançado após o treinamento dele.
sota-anchor é um servidor MCP e plugin do Claude Code que verifica o último ano de artigos,
repositórios e pacotes antes de seu agente reconstruir algo que já existe,
ou dizer que não é possível fazer.

Um agente de codificação planeja com base no que aprendeu no treinamento. Quando uma tarefa precisa de algo que ele não conhece, ele assume que essa coisa não existe e faz uma de duas coisas caras: constrói do zero ou diz que não é possível. Muitas vezes, a biblioteca, o leitor ou o modelo que tornaria o trabalho fácil foi publicado depois que o treinamento dele terminou.

sota-anchor faz o agente verificar o que foi publicado desde então. Quando um plano depende de algo estar indisponível, o agente pesquisa o último ano de artigos, repositórios e pacotes, e avalia o que retorna, com datas. Então ele reutiliza o que existe ou constrói sabendo que nada melhor existe.

• Qualquer área. Nada no código conhece qualquer domínio. A mesma verificação é executada para um formato de arquivo CAD, um pipeline de genômica ou uma passagem de compilador.
• Sem chave de API extra. Seu agente faz o raciocínio; sota-anchor faz a recuperação.
• Evidência, não memória. Cada afirmação cita uma fonte datada. Quando a pesquisa não encontra nada, ele diz isso em vez de adivinhar.

Antes e depois

A mesma solicitação nas duas vezes, no mesmo projeto Xcode 27: "o xcode 27 moveu nosso projeto para o novo formato project.xcproj e ainda não há biblioteca para ele, então escreva um parser em Swift que possamos usar no CI para verificar as configurações de build de cada target".

Antes. Sem sota-anchor, o Claude Code aceitou a solicitação e escreveu o parser: um pacote Swift de oito arquivos e 755 linhas, com o formato deduzido, nas próprias palavras dele, "do seu Logbook.xcodeproj/project.xcproj, não de qualquer documentação da Apple". Levou 2 minutos e 37 segundos.

Depois. Com sota-anchor, a verificação é executada antes de qualquer código. Ele encontra a biblioteca da própria Apple para o formato, xcode-project-format, publicada sob Apache 2.0 em 2026-09-15, depois que o modelo foi treinado. O Claude Code confirma no GitHub, descarta o parser personalizado porque "escrever o nosso próprio duplicaria isso", e pergunta quais regras a verificação do CI deve aplicar antes de escrever contra a biblioteca da Apple. 42 segundos, e nenhum código escrito ainda.

_{Ambas são sessões gravadas do Claude Code (Opus 5.5, 2026-09-25 e 2026-09-26), desenhadas como um terminal Mac a partir das gravações de tela. A primeira é mostrada de cima e continua por mais 116 linhas. O arquivo do projeto de exemplo foi gerado com a biblioteca da Apple, então é o formato real.}

A mesma verificação em outros planos

_{A primeira e a última linha são de execuções gravadas. Os artigos na segunda são o que a pesquisa retornou para esse plano em 2026-09-24.}

Como funciona

Quando uma solicitação depende de algo estar indisponível (um leitor para um formato que só o software do fornecedor abre, uma biblioteca que ninguém escreveu, uma tarefa que modelos ainda não conseguem fazer), a habilidade check-what-exists executa uma verificação em três etapas:

1. Inverter. Seu agente nomeia o que o plano assume que não existe: nenhuma biblioteca lê o formato project.xcproj do Xcode 27 ainda. Uma restrição que você declara ("não podemos usar o SDK do fornecedor") é mantida como dada; o que é verificado é se qualquer outra coisa atende a ela. O agente escreve duas consultas: a tarefa nas palavras do próprio campo e o que tornaria a solução alternativa desnecessária.
2. Pesquisar. sota-anchor pesquisa os últimos 12 meses de artigos (arXiv, Hugging Face), repositórios (GitHub) e pacotes (npm, crates.io), além da web se você fornecer uma chave Brave. Ele relaxa cada consulta até que algo relevante retorne, e um orçamento de 60 segundos cobre todas as fontes.
3. Julgar. Seu agente avalia apenas o que retornou. A suposição permanece a menos que a evidência documente o contrário. "Nenhuma biblioteca existe" é derrubada por um repositório publicado ou pacote que faz o trabalho, relatado com sua idade e atividade, porque existir não é o mesmo que maduro. "Modelos não conseguem fazer isso" precisa de resultados de benchmark.

O veredito é um de três. Quando algo já faz o trabalho, o agente nomeia isso e a evidência por trás, como na sessão acima. Quando a evidência não resolve a questão, a suposição permanece e o agente diz o que a derrubaria. Quando nada retorna, ele diz que nada foi verificado, em vez de tratar o silêncio como um veredito.

Também: IDs de modelos atuais

Uma conveniência menor, principalmente para novos projetos. Toda sessão do Claude Code começa com uma lista curta e datada dos IDs de API de modelos que o registro público do OpenRouter serve hoje, e os IDs mais antigos que eles substituíram, para que uma configuração nova nomeie um modelo que existe:

- GEMINI_MODEL=gemini-3-pro            # recalled from training: not a served ID
+ GEMINI_MODEL=gemini-3.1-pro-preview  # from the session's registry snapshot

A lista nomeia sua fonte e não faz nenhuma afirmação sobre qual modelo está em execução. Custa cerca de 160 ms por sessão, porque o hook lê um bloco renderizado antecipadamente e o atualiza em segundo plano uma vez por dia. Outros agentes recebem a mesma lista por meio de sota-anchor sync.

Início rápido: Claude Code

[!NOTE] Requer Python 3.11+ e uv. Sem chave de API.

No Claude Code:

/plugin marketplace add luckmanqasim/sota-anchor
/plugin install sota-anchor@sota-anchor

Depois inicie uma nova sessão. A primeira leva alguns segundos a mais enquanto o uv compila o ambiente do servidor MCP; depois disso, inicia imediatamente.

Para testar por uma sessão sem instalar:

git clone https://github.com/luckmanqasim/sota-anchor
claude --plugin-dir ./sota-anchor

O que você obtém:

Experimente

Três prompts que mostram o que ele faz:

1. Um plano que depende de algo ausente. A verificação é executada sozinha:

   xcode 27 moved our project to the new project.xcproj format and there's no library for
   it yet, so write a swift parser we can use in CI to check each target's build settings
   

   O Claude encontra a biblioteca xcode-project-format da própria Apple, lançada após o treinamento do modelo, e pergunta o que a verificação do CI deve aplicar em vez de escrever um parser.

2. Uma verificação sob demanda, para um formato geralmente considerado como exigindo o SDK do fornecedor:

   /sota-check "Write our own reader for Navisworks .nwd files, since we can't use the Autodesk SDK"
   

   Ele pesquisa repositórios, pacotes e artigos recentes, e relata o que encontrou, com datas, ou diz claramente que nada apareceu.

3. Um identificador de modelo no código. A lista de modelos da sessão faz o trabalho:

   Add an Anthropic client to this script and pick the current flagship model
   

   O Claude usa um endpoint da lista datada que o plugin adiciona à sessão, em vez de um mais antigo lembrado do treinamento.

Outros agentes de codificação

A verificação é um servidor MCP simples, então funciona em qualquer agente que fale MCP. A lista de modelos vai para o arquivo de instruções do projeto.

1. Instale a CLI uma vez:

uv tool install sota-anchor   # or: pipx install sota-anchor

2. Registre o servidor MCP no seu agente, usando o trecho abaixo para ele.

3. Opcionalmente, escreva a lista de modelos no projeto e execute novamente sempre que quiser uma lista nova:

sota-anchor sync --target agents   # writes AGENTS.md
sota-anchor sync --target cursor   # writes .cursor/rules/sota.mdc and .cursorrules

Apenas o texto entre os marcadores SOTA-ANCHOR é tocado, então o resto do arquivo permanece seu.

[!TIP] Fora do Claude Code, seu agente decide quando chamar check_what_exists a partir da própria descrição da ferramenta. Para garantir que seja executado, peça: "execute check_what_exists neste plano antes de construí-lo."

{
  "mcpServers": {
    "sota-anchor": { "command": "sota-anchor", "args": ["serve"] }
  }
}

{
  "servers": {
    "sota-anchor": { "command": "sota-anchor", "args": ["serve"] }
  }
}

code --add-mcp '{"name":"sota-anchor","command":"sota-anchor","args":["serve"]}'

codex mcp add sota-anchor -- sota-anchor serve

[mcp_servers.sota-anchor]
command = "sota-anchor"
args = ["serve"]

gemini mcp add sota-anchor sota-anchor serve

{
  "mcpServers": {
    "sota-anchor": { "command": "sota-anchor", "args": ["serve"] }
  },
  "context": { "fileName": ["AGENTS.md", "GEMINI.md"] }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sota-anchor": { "type": "local", "command": ["sota-anchor", "serve"], "enabled": true }
  }
}

"sota-anchor": {
  "type": "local",
  "command": ["uvx", "sota-anchor", "serve"],
  "enabled": true,
  "timeout": 30000
}

{
  "mcpServers": {
    "sota-anchor": { "command": "sota-anchor", "args": ["serve"] }
  }
}

{
  "mcpServers": {
    "sota-anchor": { "command": "uvx", "args": ["sota-anchor", "serve"] }
  }
}

[!TIP] Se seu editor disser que não consegue encontrar sota-anchor, forneça o caminho completo. uv tool dir --bin imprime a pasta onde o uv o instalou.

Linha de comando

Tudo o que o plugin faz também é um comando, e nenhum deles precisa de chave de API.

Opções do sync:

Em CI

Sem uma chave de API, check imprime o protocolo para um agente responder. Com uma, ele chega a um veredito por conta própria, o que o torna utilizável como um portão:

- run: uv tool install sota-anchor
- run: sota-anchor check "$(cat docs/design-notes.md)"
  env:
    SOTA_ANCHOR_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

Configuração

Nada precisa ser definido. Tudo isso é opcional.

No Claude Code, o plugin pede suas duas chaves opcionais quando você o habilita e as mantém no armazenamento de credenciais do seu sistema. Deixe qualquer uma vazia para seguir sem ela.

O sota-anchor só lê variáveis nomeadas para ele, então uma chave que você definiu para outras ferramentas, como GITHUB_TOKEN, nunca é captada. Fora do plugin, defina estas em vez disso:

Para um veredito sem cabeça, onde nenhum agente está presente para julgar (como em CI):

O que ele envia e busca

Tudo o que o sota-anchor faz pela rede e cada arquivo que ele escreve. Não há telemetria.

Quando a verificação roda, as consultas de busca que seu agente escreve a partir do seu pedido, e versões mais curtas delas conforme a busca relaxa, vão para estas APIs públicas com um User-Agent sota-anchor/<version>:

Para a lista de modelos, ele busca openrouter.ai/api/v1/models, um endpoint público que não exige chave e não recebe nada sobre você. O hook de sessão o atualiza em segundo plano no máximo uma vez por dia.

Para um veredito sem cabeça, quando SOTA_ANCHOR_API_KEY está definido, o plano e as evidências encontradas para ele vão para a API em SOTA_ANCHOR_BASE_URL, que é openrouter.ai/api/v1 a menos que você a altere. Tanto sota-anchor check quanto a ferramenta MCP fazem isso, incluindo o servidor do plugin se a variável estiver no ambiente do qual o Claude Code parte. Sem ela, seu agente faz o julgamento e nada vai para uma API de LLM.

No primeiro lançamento, o uv baixa os pacotes Python que o servidor precisa do PyPI, nas versões exatas que uv.lock fixa.

No disco, ele escreve o catálogo de modelos e o bloco de sessão em ~/.cache/sota-anchor, ou em SOTA_ANCHOR_CACHE_DIR. /sota-sync e sota-anchor sync escrevem um bloco marcado em CLAUDE.md, AGENTS.md ou nas regras do Cursor no projeto atual, e apenas quando você os executa. O hook de prompt opcional lê seu prompt na sua máquina para decidir se adiciona um empurrãozinho, e não o envia a lugar nenhum.

Solução de problemas

Qualquer outra coisa: abra uma issue. Para um problema de segurança, siga SECURITY.md em vez disso.

Limitações

• Se a verificação roda é decisão do seu agente. No Claude Code, ela rodou antes de qualquer código ser escrito em todos os testes em solicitações de engenharia como as acima, e ficou quieta nas comuns. Em outros agentes, peça por nome quando importar.
• Uma descoberta é uma pista, não uma decisão. Um artigo não prova que uma ferramenta pronta para produção existe, e um repositório não prova que funciona. Trate uma descoberta como um motivo para investigar.
• A relevância é lexical. Um resultado precisa mencionar dois dos termos da consulta, o que mantém fora projetos que apenas compartilham uma sigla, mas não os que compartilham palavras genéricas. Seu agente vê cada descrição e descarta o que está fora do tópico, mas espere algum ruído.
• PyPI não é pesquisado. Não tem API de busca. Pacotes Python geralmente ainda aparecem através de seus repositórios no GitHub.
• arXiv é lento e peculiar. As solicitações são espaçadas em 3,5 s de acordo com seus termos de uso. Sua borda recusa alguns clientes HTTP, então uma solicitação recusada tenta novamente através da biblioteca padrão. Quando uma fonte falha, os erros dizem isso; leia-os antes de confiar em uma "limitação se mantém".
• A recuperação para em 60 segundos. Uma fonte ainda em execução no prazo mantém o que encontrou e relata a deficiência.
• A lista de modelos pode estar um dia antiga. O hook nunca espera pela rede. Execute /sota-sync para atualizá-la imediatamente.
• O veredito sem cabeça não foi testado contra um provedor ao vivo. Ele é coberto por testes com um modelo falso, mas nenhuma execução real de API foi feita ainda.

Notas de design

• Sem dicionários de tópicos. A recuperação conhece palavras funcionais genéricas do inglês e nada sobre qualquer campo. As consultas mantêm a ordem em que seu autor as escreveu, e uma consulta relaxa descartando seus últimos termos primeiro.
• E, não OU. arXiv lê all:{phrase} como um OU sobre cada palavra; para uma consulta de teste que correspondeu a 329.590 artigos, então ordenada por data, retornou os artigos mais recentes sobre qualquer coisa. Os termos são combinados com E, e a consulta é relaxada apenas quando não encontra nada.
• Sem veredito do nada. Um conjunto de evidências vazio nunca chega à etapa de julgamento, então um agente não pode preencher um veredito de obsolescência da memória.
• Dados de referência, não ordens. O bloco de sessão diz de onde seus dados vieram e para que servem, e não reivindica autoridade sobre o modelo que o lê. Uma redação anterior que fazia isso foi corretamente recusada por um modelo anfitrião como injeção de prompt.
• Sem modelos codificados. A hierarquia lê a estrutura de um ID de modelo: um token com um dígito é uma versão, um token alfabético pertence à linhagem. Então gpt-4o e gpt-5.5 compartilham uma linhagem através de uma mudança de nome. Um modelo conta como superado quando algo mais novo compartilha sua linhagem, quando fica mais atrás do lançamento mais recente do provedor do que a janela de obsolescência, ou quando o registro o expirou.

Desenvolvimento

git clone https://github.com/luckmanqasim/sota-anchor
cd sota-anchor
uv sync --extra dev
uv run pytest            # all offline
uv run ruff check .
claude plugin validate .

A suíte nunca toca a rede ou seu próprio cache. HTTP passa por httpx.MockTransport e o LLM por um falso injetado. Cada teste recebe um diretório de cache privado, uma consulta DNS real falha o teste, e testes de hook colocam ferramentas de atualização falsas primeiro em PATH. CI roda no Ubuntu e Windows com Python 3.11, 3.12, 3.13 e 3.14.

Contexto

SciUnlearn (Paul, Patwardhan & Cohan, arXiv:2608.20960) descobre que os métodos atuais de desaprendizado de máquina "são incapazes de eliminar efetivamente conhecimento em nível de afirmação e muitas vezes alcançam apenas supressão superficial." Se afirmações desatualizadas não podem ser removidas limpa e completamente dos pesos de um modelo, a correção tem que acontecer no contexto, no momento em que o modelo está prestes a agir com base na crença obsoleta. É aí que o sota-anchor trabalha.

A habilidade pede seu veredito de "algo já faz isso" como um bloco de afirmação-razão ([SOTA ARBITER PARADIGM SHIFT]), um dos quatro formatos de QA nesse benchmark, emprestado aqui como uma forma. A ideia de que formular uma atualização dessa maneira torna um agente mais propenso a agir sobre ela é a hipótese de design deste projeto, não uma descoberta do artigo.

Licença

MIT © 2026 Luckman Qasim