Plugin para Claude Code e Codex

Instalação

O plugin fica em dois repositórios do GitHub, um para o Claude Code e outro para o Codex. Os dois têm o mesmo conteúdo e o mesmo número de versão. A diferença é só como cada ferramenta os carrega. Instale o que corresponde à sua ferramenta, porque o outro não carregaria.

Selecione a sua ferramenta e rode os dois comandos, um depois do outro:

O primeiro comando adiciona o catálogo de plugins (o marketplace) do GitHub. Depois, o segundo instala o html2wp a partir dele. O Codex precisa de um repositório próprio porque encontra plugins pelo arquivo .agents/plugins/marketplace.json, e o repositório do Claude Code não tem esse arquivo.

Atualizações

O comando de atualização tem um nome diferente em cada ferramenta. No Codex é upgrade, no Claude Code é update:

Para ver a versão instalada, rode codex plugin list no Codex. No Claude Code, vá em /plugin → Marketplaces → html2wp.

Se a versão no Codex não mudou depois de uma atualização, o Codex tem uma cópia antiga guardada. Apague essa cópia e instale o plugin de novo:

Se isso também não resolver, o Codex pode ter outra cópia mais antiga, de uma instalação manual. O comando codex plugin marketplace list mostra todos os catálogos. Se aparecer html2wp@<other-name>, remova com codex plugin remove html2wp@<that-name>.

A maior parte do trabalho acontece no serviço html2wp, e o serviço se atualiza sozinho, então a sua próxima conversão já roda a versão nova. Você só precisa atualizar a parte que roda no seu computador: as verificações, os scripts e o filtro de dados enviados. O que mudou em cada versão está no histórico de commits no GitHub.

Requisitos

Você não precisa conferir isso sozinho. Quando você inicia uma conversão, o plugin primeiro verifica o seu computador e lista o que falta:

Node.js                ok        v22.14.0
Python                 ok        3.12.4
Playwright             MISSING   mirroring, prerendering and every screenshot
Docker                 NOT RUNNING  installed, but the daemon is not up

Para pacotes que se instalam só na sua pasta de usuário, como o Playwright ou o navegador chromium, o plugin se oferece para instalar por você. Ele pergunta antes de cada comando. O que muda o sistema inteiro, como o Docker Desktop ou um Node.js mais novo, ele só informa, e depois espera até você instalar.

Se você quiser instalar os pacotes Python à mão:

Qual modelo usar

Durante uma conversão, a IA precisa tomar muitas decisões. Por exemplo: qual página é a inicial, por que uma verificação falhou ou se um cliente sequer notaria a diferença entre duas capturas de tela. Por isso, a escolha do modelo afeta o resultado mais do que qualquer outra configuração.

No Claude Code, o Opus 5 faz o trabalho e o Fable 5 é consultado nas decisões importantes, que é onde uma conversão mais costuma dar errado.

Chave de licença

Na versão gratuita você não precisa de chave, então pule esta seção. Se você tem uma licença, salve a chave no seu computador antes da primeira conversão. Você faz isso uma vez só, de qualquer pasta:

Você também pode passar a chave na variável de ambiente H2WP_KEY, que tem prioridade sobre o arquivo. O arquivo é mais seguro, porque assim a chave não vai parar no histórico do terminal.

O arquivo recebe a chave de licença do html2wp que você ganha ao comprar o Pro. Uma chave do Visual Edit Pro não vai ali. Essa você insere no plugin Visual Edit, no site que edita, e ela não funciona para conversões.

Para saber se uma chave é válida, para que serve e até quando, rode npx html2wp-license YOUR-KEY. A verificação de chave na página de licenças explica o que o resultado significa. O que uma licença inclui e como comprar está na página de licenças.

Converter um projeto

Abra um terminal na pasta do projeto que você quer converter e inicie o seu agente ali:

Se você usa o Claude Code, digite claude em vez de codex na última linha.

Depois, dê ao agente um único comando:

Só isso. Você não roda npm install nem npm run build, e não configura nada. Projetos do Bolt, v0, shadcn ou uma exportação do Next.js convertem do mesmo jeito. Você também pode digitar só /html2wp:html2wp no Claude Code, ou pedir ao Codex que use o html2wp. O plugin então pergunta o que converter.

Os primeiros minutos de uma conversão

> convert this project

  Checking this machine first…
    Node.js     ok    v22.14.0
    Playwright  MISSING
  Two Python packages are missing. Shall I install them? (they go in your
  user directory, no root)

> yes

  … installed. Building the project, then prerendering it.
  7 routes found: /, /about, /pricing, /blog, /blog/launch, /contact, /faq
  Decided: /blog is the listing, /blog/launch an article, the rest are pages.
  Written to the manifest; carrying on.

Nas últimas linhas, o plugin registrou como classificou as páginas: /blog é a listagem de artigos, /blog/launch é um artigo e o resto são páginas normais. Confira essa decisão no site pronto, no final.

Outras entradas

O comando convert this project converte a pasta em que você está. Se os arquivos estiverem em outro lugar, digite o caminho até eles, por exemplo convert ./dist.

A entrada sempre precisa estar no seu disco. O plugin não converte o endereço de um site no ar. Ele precisa dos arquivos de que o site é feito, não do que o navegador mostra.

Como um projeto do Lovable é convertido

Um app do Lovable é feito em React. O index.html dele tem só um elemento vazio e um script, e a página só ganha vida no navegador. Por isso, o plugin primeiro gera o build do projeto, abre num navegador de verdade e salva cada página como HTML pronto. Ele também captura o conteúdo que só aparece depois que os scripts rodam, como acordeões abertos ou menus suspensos. Depois, faz o tema a partir dessas páginas. Os detalhes estão no guia Lovable para WordPress.

O que ele decide por você

Qual página é qual

Uma decisão tem o maior efeito no resultado: qual página é a inicial, qual é a listagem de artigos, quais são artigos e quais são produtos. O plugin descobre isso pelo código das páginas, registra e segue sem perguntar. Ele só para quando não consegue decidir. Por exemplo, quando o site tem mais páginas do que o seu limite permite, ou quando duas páginas parecem ser a mesma.

Se ele errar, a correção é barata. Você corrige a classificação e roda a conversão de novo. Isso é uma reexecução, e ela não conta no seu limite de conversões.

Depois, quase tudo roda sozinho

O Flash leva cerca de meia hora, o Full cerca de uma hora, dependendo do número de páginas e da velocidade do seu computador. Enquanto isso, o plugin gera o site, compara com o original e envia ao serviço html2wp para a conversão. Depois, instala o tema pronto num WordPress temporário no Docker do seu computador e testa ali.

A revisão que você não pode pular

No final, o plugin mostra cada página ao lado da original numa só imagem. Olhe cada imagem e diga o que você vê.

O que você recebe

• O tema como arquivo ZIP. Você envia para o WordPress em Aparência → Temas → Adicionar novo tema → Enviar tema. O plugin simplesmente não gera um tema quebrado: por exemplo, se o PHP tiver erro de sintaxe, se faltar conteúdo, se a imagem de capa do tema tiver o tamanho errado ou se não der para comprar nada na loja.
• O relatório CONVERSION-REPORT.md na mesma pasta do ZIP. Ele lista as páginas convertidas, os menus ligados, tudo o que você encontrou na revisão, cada aviso da conversão e o que ainda falta fazer.
• Um link para o Visual Edit Lite, o editor gratuito para editar apontando e clicando. O editor não faz parte do tema, e o tema funciona sem ele. Já o Visual Edit Pro é uma licença paga à parte.

O tema é independente. Páginas, blog, formulários, menus, SEO e redirecionamentos fazem parte do código dele e funcionam sem plugins. O código é PHP, CSS e JavaScript legível. Ele pertence a você e não fica preso a nós. O tema não se conecta a lugar nenhum. Como editá-lo clicando está descrito na parte sobre o Visual Edit na documentação do app.

O que sai do seu computador

Quem faz o trabalho de navegador é o seu computador: gerar as páginas, comparar capturas de tela e rodar um WordPress temporário no Docker para as verificações finais. O tema em si é feito pelo serviço html2wp. Por isso, o plugin envia a ele o site gerado e recebe o tema de volta.

As verificações do tema rodam do seu lado, então o serviço não vê os resultados delas. Por isso, no final, o plugin os envia ao serviço. Isso é obrigatório: o serviço não inicia a próxima conversão até a anterior enviar os resultados.

• O que é enviado: os nomes das verificações, se passaram, contagens de páginas, a pior porcentagem de correspondência e os nomes curtos das páginas que falharam, como about ou pricing.
• O que não é enviado: o endereço ou o domínio do site, código, texto, capturas de tela, caminhos de arquivo, a chave de licença ou o nome do site. Só campos predefinidos são enviados, nada mais.
• Confira você mesmo: o comando send-verdicts.sh <workspace> --dry-run imprime exatamente o que seria enviado, mas não envia nada. É um script curto que você pode ler.

O plugin não envia nenhum outro dado, e o tema pronto não envia nada. A descrição completa, incluindo por quanto tempo guardamos os dados, está na página de privacidade.

Como relatar um bug

Se o próprio conversor errar, relate com este comando:

Uma pessoa lê cada relato. A correção depois entra no serviço, então ajuda todos os usuários.