Turn HTML into valid WordPress blocks, from inside your AI agent.

Common questions

What does it output?

Real WordPress blocks, the same kind you would add in the block editor by hand. Send it page content and you get plain, native Gutenberg blocks (Cover, Columns, Buttons and the rest) that anyone can edit, with the CSS your generator wrote carried into each block's own styling controls. Send it a design and you get a registered block: one named, reusable block written into your plugin, with only the fields you allow editable, that appears in the inserter like any core block. Nothing proprietary to keep installed.

Do I need to change how I generate content?

One change: stop asking your AI to write WordPress block markup. Give Block Runner the HTML your AI agent or design tool produced and let the agent decide what it should become. Block Runner builds the Gutenberg blocks and checks them. It wants HTML that was authored, not HTML scraped from a rendered page.

Do I need an AI agent to use it?

No, but that is where it does its best work. On its own it is a command-line tool for scripts and CI; that is the dashed line on the chart above. Under an AI agent it does the whole job. Run npx block-runner skill --install once. Claude Code, Codex, Cursor or any agentic editor learns the skill, works out whether you want page content, a reusable block or a validation pass, and runs the right commands.

Can I see the plan before anything is written into my code?

Yes. Before it writes a reusable block, Block Runner shows you what it is about to do: the block's name, which parts editors can change, what stays fixed, which files it will create, and any warnings. The write is tied to that exact preview, so it cannot quietly write something different. Whether your agent stops to show you the preview is down to the agent and how you have set it up; the skill tells it to.

Does it read my theme.json or theme styles?

Yes. Your theme's own colours, font sizes and spacing get used instead of hard-coded values. Point it at a theme.json file, a live site, or a Wesper context manifest, and off-theme values snap onto your presets: colours become palette slugs, sizes become your font-size and spacing slugs. It reads settings only, not your theme's CSS. Resolution is off by default, so pass a resolver as well as the file: --token-resolver file --theme-json path/to/theme.json, or wpcli, rest, or context to read from a live site. On its own --theme-json does nothing, because the resolver defaults to noop.

How does it decide a block is valid?

It uses the same parser the WordPress editor uses. Every result runs through headless Gutenberg, so valid means what the editor means: markup that matches each block's save() output, and correct nesting. Attachment ids are a separate job, media resolution rather than validity, so with the default noop resolver you get valid blocks and no ids.

Can I run it in CI?

Yes. It is a command-line tool, so it runs anywhere a shell does: GitHub Actions, GitLab CI, CircleCI, pre-commit hooks, or your own scripts. It exits 0 when clean and 1 when it finds problems, so invalid blocks fail the build instead of shipping (2 is a usage or IO error, 3 a headless boot failure). Add --strict to treat warnings, such as unresolved media, as failures too.

Is it really open source?

Yes. GPL-2.0-or-later on GitHub, free to use, an npm package you drop into your own pipeline. We built it for our own autonomous experiments on Accelerate, then opened it up.