Plugin for Claude Code and Codex

Install

The plugin lives in two GitHub repositories, one for Claude Code and one for Codex. Both have the same content and the same version number. They differ only in how each tool loads them. Install the one that belongs to your tool, because the other one would not load.

Switch to your tool and run both commands, one after the other:

The first command adds the plugin catalogue (the marketplace) from GitHub. Then the second one installs html2wp from it. Codex needs its own repository because it finds plugins through the file .agents/plugins/marketplace.json, and the Claude Code repository does not have that file.

Updates

The update command has a different name in each tool. In Codex it is upgrade, in Claude Code it is update:

To see the installed version, run codex plugin list in Codex. In Claude Code, go to /plugin → Marketplaces → html2wp.

If the version in Codex did not change after an update, Codex has an old copy stored. Delete it and install the plugin again:

If that does not help either, Codex may also have a different, older copy from a manual install. The command codex plugin marketplace list prints every catalogue. If you see html2wp@<other-name> there, remove it with codex plugin remove html2wp@<that-name>.

Most of the work happens in the html2wp service, and the service updates itself, so your next conversion already runs the new version. You only have to update the part that runs on your computer: the checks, the scripts and the filter for outgoing data. What changed in each version is in the commit history on GitHub.

Requirements

You don't have to check this yourself. When you start a conversion, the plugin first checks your computer and lists what is missing:

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

For packages that install only into your user folder, such as Playwright or the chromium browser, the plugin offers to install them for you. It asks before every command. Things that change the whole system, such as Docker Desktop or a newer Node.js, it only reports, and then it waits until you install them yourself.

If you want to install the Python packages by hand:

Which model to use

During a conversion the AI has to make a lot of decisions. For example: which page is the home page, why a check failed, or whether a client would even notice the difference between two screenshots. So the choice of model affects the result more than any other setting.

In Claude Code, Opus 5 does the work and Fable 5 is consulted on the important decisions, which is where a conversion most often goes wrong.

Licence key

On the free tier you don't need a key, so skip this section. If you have a licence, save the key on your computer before your first conversion. You only do this once, from any folder:

You can also pass the key in the environment variable H2WP_KEY, which takes precedence over the file. The file is safer, because then the key does not end up in your terminal history.

The file takes the html2wp licence key you get when you buy Pro. A Visual Edit Pro key does not go there. You enter that one in the Visual Edit plugin on the site you edit, and it does not work for conversions.

To find out whether a key is valid, what you can use it for and until when, run npx html2wp-license YOUR-KEY. The key check on the licences page explains what the result means. What a licence includes and how to buy one is on the licences page.

Converting a project

Open a terminal in the folder of the project you want to convert, and start your agent there:

If you use Claude Code, type claude instead of codex on the last line.

Then give the agent a single command:

That is all. You don't run npm install or npm run build, and you don't configure anything. Projects from Bolt, v0, shadcn or a Next.js export convert the same way. You can also type just /html2wp:html2wp in Claude Code, or ask Codex to use html2wp. The plugin then asks you what to convert.

The first minutes of a conversion

> 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.

In the last lines the plugin recorded how it sorted the pages: /blog is the article listing, /blog/launch is an article and the rest are regular pages. Check this decision on the finished site at the end.

Other input

The command convert this project converts the folder you are in. If the files are somewhere else, type the path to them, for example convert ./dist.

The input always has to be on your disk. The plugin does not convert the address of a live site. It needs the files the site is built from, not what the browser shows.

How a Lovable project converts

A Lovable app is built in React. Its index.html holds only an empty element and a script, and the page comes to life only in the browser. So the plugin first builds the project, opens it in a real browser and saves each page as finished HTML. It also captures content that appears only after the scripts run, such as open accordions or dropdown menus. Then it makes the theme from these pages. The details are in the Lovable to WordPress guide.

What it decides for you

Which page is which

One decision has the biggest effect on the result: which page is the home page, which is the article listing, which are articles and which are products. The plugin works this out from the page code, writes it down and carries on without asking. It stops only when it cannot decide. For example, when the site has more pages than your limit allows, or when two pages look like the same one.

If it gets this wrong, the fix is cheap. You correct the sorting and run the conversion again. That is a re-run, and it does not count against your conversion limit.

Then it mostly runs on its own

Flash takes about half an hour, Full about an hour, depending on the number of pages and how fast your computer is. Meanwhile the plugin builds the site, compares it with the original and sends it to the html2wp service for conversion. After that it installs the finished theme into a temporary WordPress in Docker on your computer and tests it there.

The review you can't skip

At the end the plugin shows you each page next to the original in one image. Look at every image and say what you see.

What you get

• The theme as a ZIP file. You upload it to WordPress under Appearance → Themes → Add New → Upload Theme. The plugin does not build a broken theme at all: for example, if the PHP had a syntax error, content was missing, the theme screenshot had the wrong size, or you could not buy anything in the shop.
• The report CONVERSION-REPORT.md in the same folder as the ZIP. It lists the converted pages, the wired-up menus, everything you found in the review, every warning from the conversion and what is still left to do.
• A link to Visual Edit Lite, the free editor for point-and-click edits. The editor is not part of the theme, and the theme works without it. Visual Edit Pro is a separate paid licence.

The theme is standalone. Pages, blog, forms, menus, SEO and redirects are part of its code and work without plugins. The code is readable PHP, CSS and JavaScript. It belongs to you and is not tied to us. The theme does not connect anywhere. How to edit it by clicking is described in the Visual Edit part of the app documentation.

What leaves your computer

Your computer does the browser work: building the pages, comparing screenshots and running a temporary WordPress in Docker for the final checks. The theme itself is made by the html2wp service. So the plugin sends it the built site and gets the theme back.

The theme checks run on your side, so the service does not see their results. At the end the plugin therefore sends them to it. This is required: the service does not start the next conversion until the previous one has sent its results.

• What is sent: the names of the checks, whether they passed, page counts, the worst match percentage and the short names of the pages that failed, such as about or pricing.
• What is not sent: the site's address or domain, code, text, screenshots, file paths, the licence key or the site name. The plugin sends only predefined fields, nothing else.
• Check it yourself: the command send-verdicts.sh <workspace> --dry-run prints exactly what would be sent, but sends nothing. It is one short script you can read.

The plugin sends no other data, and the finished theme sends nothing at all. The full description, including how long we keep the data, is on the privacy page.

Reporting a bug

If the converter itself makes a mistake, report it with this command:

A person reads every report. The fix then goes into the service, so it helps every user.