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.
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:
- CLI only: measurements, gate and report, no model.
- 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.
- 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 theAudittype inpackages/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--judgeit 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:
| Command | Steps | Writes |
|---|---|---|
/restyle:research <target> | research and brief | design/research/, design/BRIEF.md |
/restyle:critique <target> | audit and critique | restyle-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 report | restyle-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 ./
| Flag | Meaning |
|---|---|
--live | required; 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-run | print 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 nestedrestyle agentrun. - 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-criticandblind-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.