Wahajolla/annotate

O que annotate faz?

O usuário clica em um elemento de uma página, escreve uma nota, e o Claude recebe a nota com um seletor, texto próximo, bounding box e URL, para que possa encontrar o elemento no código e corrigi-lo.

Construído sobre o Agentation: o toolbar agentation (React 18+, apenas desktop) e o servidor de notas agentation-mcp (API HTTP em SQLite, mais ferramentas MCP opcionais).

Escolha o modo primeiro

Pergunte ao usuário se não estiver claro:

• Local: apenas o usuário e o Claude, nesta máquina. O servidor de notas roda em localhost:4747. Nada é implantado. Este é o padrão.
• Compartilhado: colegas comentam em um site hospedado, e todos veem as notas de todos. Precisa de um servidor de notas em um host HTTPS público. Veja references/shared.md. Essa página descreve a arquitetura e os requisitos; o usuário escolhe a hospedagem.

Onde o toolbar é inserido

Escolha com base no que é a página. As mesmas opções funcionam em ambos os modos; apenas endpoint e session mudam.

1. Dentro do app React do usuário. npm i -D agentation, então renderize-o ao lado do app, restrito para nunca chegar à produção:

   {import.meta.env.DEV && <Agentation endpoint="http://localhost:4747" />}
   

   Adicione useHashLocation para roteadores hash e appName para rotular o feedback.
2. Qualquer página HTML que ele controla, React ou não. Adicione uma tag script. O loader monta o toolbar em seu próprio contêiner e sua própria raiz React, portanto não interfere na página hospedeira:

   <script type="module" src="https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/annotator.js?endpoint=http://localhost:4747"></script>
   

   Parâmetros de consulta: endpoint, session, app, hash=1. Alternativamente, defina window.ANNOTATOR_CONFIG = {endpoint, session, app, hash} antes do script carregar.
3. Qualquer site, sem tocar no código dele. Use um bookmarklet. Dê ao usuário esta linha para salvar como favorito; clicar nela alterna o toolbar entre ligado e desligado:

   javascript:(()=>{const s=document.createElement('script');s.type='module';s.src='https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/annotator.js?endpoint=http://localhost:4747&t='+Date.now();document.head.appendChild(s)})()
   

   Limites a informar ao usuário:
   • Sites com uma Política de Segurança de Conteúdo (CSP) restrita (GitHub, muitos bancos e grandes aplicativos) bloqueiam os scripts injetados, portanto o toolbar não aparecerá neles.
   • Em um site público https:// que se comunica com localhost, o navegador pode solicitar acesso à rede local: permita.
   • O servidor de notas deve permitir a origem desse site (veja CORS abaixo).
   • As notas estão vinculadas à URL do site, e os rascunhos locais do toolbar ficam no localStorage desse site.
4. Extensão Chrome. Esta é a maneira mais robusta de anotar qualquer site. Ela alterna com um clique ou Alt+Shift+A, funciona em sites com CSP restrita (GitHub, Notion, etc.) e não precisa de configuração CORS: as requisições passam pela extensão. Instalação: baixe annotator-extension.zip de https://github.com/Wahajolla/annotator-skill/releases/latest, depois chrome://extensions → Modo do desenvolvedor → Carregar sem compactação. O servidor de notas é definido nas opções da extensão. O padrão é http://localhost:4747; para o modo compartilhado, use a URL hospedada mais o id da sessão. A sincronização ao vivo é por polling a cada 5 segundos. Se o servidor de notas estiver inacessível, a extensão mostra um cartão "Servidor de notas está offline" com o comando de inicialização, e #annotator-ext-root recebe data-annotator-server="offline" ("online" quando responder): se você estiver controlando o navegador, verifique antes de dizer ao usuário que suas notas foram salvas. Nas opções, "Entrar com GitHub" assina cada nota com o login do usuário, para que as notas dos colegas mostrem quem as deixou.

Sem endpoint o toolbar funciona apenas em modo cópia. As notas ficam no navegador, e o usuário pressiona Copiar e cola o markdown no chat. Isso não precisa de servidor, então use quando o usuário quiser apenas uma anotação pontual.

Modo local

1. Execute o servidor de notas. Escolha um:

   • MCP (melhor para uso repetido). Com a permissão do usuário: claude mcp add agentation -- npx -y agentation-mcp server. O Claude Code então o inicia a cada sessão, e as ferramentas agentation_* aparecem após uma reinicialização: get_all_pending, resolve, reply e watch_annotations para loops automáticos.
   • HTTP puro (sem reinicialização). Execute npx -y agentation-mcp server como um comando em segundo plano e leia as notas via HTTP (veja abaixo).

   Verifique com curl http://localhost:4747/health, que deve retornar {"status":"ok"}.

2. CORS. Por padrão, apenas origens de desenvolvimento são permitidas (localhost, *.localhost, 127.0.0.1, IPs privados, .local, .test, .internal). Para um bookmarklet em um site público, inicie o servidor com AGENTATION_CORS_ORIGINS=https://esse-site.com (origens exatas, separadas por vírgula). * também funciona, mas permite que qualquer aba aberta escreva notas, então prefira origens exatas.

3. Coloque o toolbar na página usando uma das opções acima, com endpoint=http://localhost:4747.

4. Verifique. Adicione uma nota de teste através do toolbar, verifique se curl localhost:4747/pending a mostra, depois a exclua.

As notas persistem em ~/.agentation/store.db.

Lendo e agindo sobre as notas (ambos os modos)

• MCP: agentation_get_all_pending, depois corrija o código, depois agentation_resolve com um breve resumo.
• HTTP: GET /pending (todas as notas abertas), GET /sessions, GET /sessions/:id. Após corrigir uma nota, envie PATCH /annotations/:id com {"status":"resolved"}.
• Quem escreveu: notas da extensão Chrome com login no GitHub carregam authorId: "github:<login>", e por padrão o comentário começa com @<login>: . Uma nota sem authorId é anônima (qualquer outra forma de carregar o toolbar). Mencione o autor ao reportar.
• Campos úteis são comment, url, element, elementPath, fullPath, nearbyText, selectedText, boundingBox e reactComponents (apenas builds de desenvolvimento).
• Deixe o usuário decidir antes de excluir qualquer coisa.

Mostrando notas para capturas de tela

O Agentation mostra o texto de uma nota apenas enquanto você passa o mouse sobre o marcador. Para mostrar todas de uma vez, use a camada de notas: um contorno, um número e um cartão de texto completo para cada nota. Quando terminar de desenhar, <html> recebe data-annotator-notes="<contagem>".

• O usuário, no Chrome: Alt+Shift+N na extensão (ou clique com o botão direito no ícone → Mostrar todas as notas nesta página).
• Você, em uma página que está controlando (Playwright, Chrome DevTools MCP, etc.): defina suas próprias notas e carregue a camada, depois aguarde o atributo e faça a captura de tela:

  window.ANNOTATOR_NOTES = [
    { selector: "h1", comment: "Muito longo. Faça “Preços simples”", author: "claude" },
    { selector: "#cta", comment: "Use o azul da marca" },
  ]
  const s = document.createElement("script"); s.type = "module"
  s.src = "https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/notes.js?t=" + Date.now()
  document.head.appendChild(s)
  

  Cada nota aceita selector (ou boundingBox: {x, y, width, height} em coordenadas da página), comment e um author opcional. Notas cujo seletor não corresponde a nada são ignoradas com um aviso no console, então verifique se a contagem corresponde. Em vez de ANNOTATOR_NOTES, passe ?endpoint=http://localhost:4747 para mostrar as notas do servidor para aquela página; adicione &all=1 para incluir as resolvidas. Carregá-lo novamente com um novo t oculta a camada.
• Sites com CSP restrita (GitHub e outros) bloqueiam esse script. No Playwright, crie o contexto com bypassCSP: true; caso contrário, use a extensão.
• Para tornar suas notas reais (o usuário as vê também no toolbar dele, e pode resolvê-las): POST /sessions com {"url": "<url da página>"} e depois POST /sessions/:id/annotations com comment, element, elementPath (um seletor CSS), url, boundingBox e x/y (coordenadas da página). Em seguida, mostre-as com ?endpoint=…. Pergunte ao usuário primeiro: elas se tornam notas compartilhadas.

Armadilhas

• O toolbar é apenas para desktop.
• O servidor de notas não tem autenticação, apenas CORS. Qualquer pessoa cuja origem do navegador seja permitida pode escrever e excluir notas.
• useHashLocation mantém notas por #rota. Ativá-lo depois não move notas existentes.
• O Agentation é licenciado sob PolyForm Shield, o que é adequado para uso interno de feedback.