restyle docs: the CLI, the Claude Code plugin and the SDK path

The CLI measures and gates a page and calls no model. The plugin runs the research, critique, re-theme and judging steps in your own Claude Code session. The Agent SDK path runs the same steps headless, on your API key, with a hard budget cap.

Get the code

restyle is not on npm yet. Clone the repository and install once; every command below assumes the clone sits in ./restyle.

Clone and install
git clone <restyle-repo-url>
pnpm --dir ./restyle install

This page is rendered from docs/USAGE.md in the repository, with paths pointing at a fresh clone in ./restyle.

restyle has two halves. The CLI (packages/cli) screenshots, measures, lints and gates a page; it calls no model. The LLM steps (research brief, critic pick, critique, re-theme, blinded judge) run either in your own Claude Code session through the plugin, or, optionally, headless through the Claude Agent SDK on an API key.

There are three ways to use it:

  1. CLI only: measurements, gate and report, no model.
  2. The Claude Code plugin: the full pipeline in your Claude Code session. restyle makes no API calls of its own; the work counts against your Claude Code plan like any other session.
  3. The Agent SDK path: the same pipeline without a person present. It spends API credit, is off by default, and needs a budget cap.

Setup (once)

Requirements: Node 22 or later, pnpm 9, and this repository at ./restyle.

pnpm --dir ./restyle install
node ./restyle/packages/cli/bin/restyle.mjs --help

If a command fails because no browser is installed, run pnpm --dir ./restyle/packages/cli exec playwright install chromium.

Below, restyle is short for node ./restyle/packages/cli/bin/restyle.mjs. From inside the repository, pnpm restyle <command> also works. Run commands from the root of the project you are working on; outputs land in the directories you name with --out.

1. CLI only

A target is a URL, a local HTML file, or a local directory of static files (the CLI serves it). For a site that needs a build or dev server, start it and pass its local URL.

# Audit the current site: screenshots at 375/768/1440, tells, crops, contrast, axe, Lighthouse
restyle audit https://their-site.example --label before --niche "family dental clinic" --out restyle-out/before

# Optional: crawl the client, competitors and references (comma-separated, no spaces)
restyle research https://their-site.example --competitors https://a.example,https://b.example --refs https://c.example --out design/research
# -> design/research/research.json + design/research/<site>/shots/; bot walls are recorded ok:false, reason "blocked"
# Add sites later without recrawling the rest
restyle research https://their-site.example --refs https://d.example --out design/research --append

# Check a design direction (contrast, second-order looks) and compile it to CSS tokens
restyle tokens design/direction.json --out design/theme.css

# After you change the site: audit again and apply the pass/fail gate (exit 0 pass, 1 fail)
restyle gate https://their-site.example --baseline restyle-out/before/audit.json --out restyle-out/after-1

# Before/after report (the folder is self-contained and can be deployed)
restyle report --before restyle-out/before --after restyle-out/after-1 --out restyle-out/report/index.html

Outputs:

  • restyle-out/before/audit.json: every finding with its rule, selector, width and crop path, plus tell counts and metrics. The format is the Audit type in packages/cli/src/types.ts.
  • restyle-out/after-1/gate.json: each check with its value, bar and pass/fail.
  • restyle-out/report/index.html: the before/after report. Without --judge it says no blinded judgement was run.

restyle tokens exits non-zero on a contrast failure or a second-order look (cream with serif and terracotta, near-black with one acid accent, broadsheet hairlines with zero radius). To keep a second-order look on purpose, pass --allow-second-order "<reason>"; the reason is written into the CSS.

A direction file looks like plugin/skills/restyle/templates/direction.example.json.

2. The Claude Code plugin

Install from this repository as a local marketplace, inside Claude Code:

/plugin marketplace add ./restyle
/plugin install restyle@restyle

or from a shell:

claude plugin marketplace add ./restyle
claude plugin install restyle@restyle

Then start a new session or run /reload-plugins. A marketplace added from a local path loads the plugin from the repository in place, so edits to plugin/ apply on the next reload and the plugin finds the CLI at ../packages/cli. If you install a copy elsewhere, set the RESTYLE_HOME environment variable to ./restyle.

Run it from the root of the project you want to redesign:

/restyle:restyle https://their-site.example --niche "family dental clinic, Leeds" --competitors https://a.example https://b.example https://c.example

The target can also be a local path. Without --competitors, the research step finds competitors itself. Asking in plain words ("make this site look less AI", "run a design audit of http://localhost:3000") also loads the skill.

Single steps:

CommandStepsWrites
/restyle:research <target>research and briefdesign/research/, design/BRIEF.md
/restyle:critique <target>audit and critiquerestyle-out/before/, design/CRITIQUE.md
/restyle:retheme <target>tokens, code and copy changes, gate loop (at most 3 rounds)design/theme.css, code edits, design/CHANGES.md, restyle-out/after-<n>/
/restyle:report [after-dir]blinded judge and reportrestyle-out/judge/judge.json, restyle-out/report/index.html

The full pipeline also writes design/directions/*.json, design/direction.json, design/CRITIC_PICK.md (the fresh critic's verbatim reply), design/OPEN_QUESTIONS.md (facts only the owner can supply) and, if the gate still fails after 3 rounds, design/GATE_REPORT.md.

Two subagents come with the plugin, each limited to the Read tool: restyle:design-critic picks a direction given only the brief, the direction files and the reference screenshots; restyle:blind-judge compares screenshots labelled A and B. The CLI does the blinding (restyle agent blind, random order then reversed) and the unblinding (restyle agent unblind), so the order is never chosen by a model. If the two orderings disagree, the verdict is a tie.

Claude Code asks before each node .../restyle.mjs command unless you allow it in your permission settings.

If the target is a URL and no code is available, the plugin stops after the critique and tokens and writes design/CHANGES.md as a list of proposed changes; there is no gate run or report.

3. The Agent SDK path (optional, spends API credit)

This runs the plugin's own skill and prompt files headless through @anthropic-ai/claude-agent-sdk (an optional dependency of the CLI). Look at the plan first; a dry run makes no API call:

restyle agent https://their-site.example --niche "family dental clinic, Leeds" --competitors https://a.example https://b.example --dry-run

A live run refuses to start unless all three are present: --live, the ANTHROPIC_API_KEY environment variable, and --budget-usd.

restyle agent https://their-site.example --live --budget-usd 5 --niche "family dental clinic, Leeds" --competitors https://a.example https://b.example --source ./
FlagMeaning
--liverequired; confirms the run may spend API credit
--budget-usd <n>required; hard cap in US dollars, passed to the SDK's maxBudgetUsd. The run stops when spend passes it
--model <id>claude-sonnet-5-5 (default) or claude-opus-5-5
--max-turns <n>turn cap, default 150, at most 400
--competitors <url> ...competitor URLs, space-separated
--niche <niche>the business niche
--source <dir>the site's code, when the target is a URL
--project <dir>where design/ and restyle-out/ go (default: the current directory)
--dry-runprint the plan and the resolved prompts, then exit

What the agent may do, enforced in code (packages/cli/src/agent/policy.ts), not by the prompt:

  • Bash runs only node <repo>/packages/cli/bin/restyle.mjs ..., with no pipes, chaining, redirection or $ expansion, and never a nested restyle agent run.
  • Write and Edit only inside the project directory (and --source). Read, Glob and Grep also in the restyle repository and the OS temp directory (where blinded screenshots go).
  • WebFetch for http(s) URLs. No WebSearch.
  • Subagents: only design-critic and blind-judge, each with the Read tool only.
  • User and project Claude Code settings are not loaded, so their allow rules do not widen this.

At the end it prints one line, for example cost: $1.2345 of $5.00 budget · 64 turns · model claude-sonnet-5-5 · result success, and appends it with a timestamp to restyle-out/agent-cost.log. The figure is the SDK's estimate, not an invoice. The exit code is 0 only when the run finished normally; a run stopped by the budget or turn cap exits 1 and says why in the result field.