Variate: The Agent Skill That Puts 4 Real UI Variants on Your Localhost

If you've ever asked a coding agent to "try a different hero section" and gotten back a wall of text describing three options you have to imagine, Variate is built for exactly that moment. It's a small, zero-dependency agent skill — installable in Claude Code, Codex CLI, or opencode — that writes four complete, working versions of one file in your project and lets you switch between them on the localhost you're already staring at, using the arrow keys.

There's no separate design canvas, no Figma import, and nothing to keep in sync. The variant you land on is the code, because it was never anything else.

TL;DR

The problem Variate is solving

Ask most coding agents for design alternatives and you get one of two bad outcomes. Either the agent describes options in prose ("Option A uses a card grid, Option B uses a split layout...") and you're mentally rendering CSS in your head, or it hands you off to a separate preview tool — a hosted canvas, a Figma-style mockup — that has to be translated back into your actual codebase once you pick a winner. Both add a translation step between "I like this" and "this is now my code."

Variate's README states the whole pitch in one sentence:

"Your agent writes four real versions of one file; arrow keys flip them on the localhost you are already looking at. The one you keep is the code."

That's the entire mental model. No abstraction layer, no export step.

How it actually works under the hood

Variate's tech stack, per its own README, is deliberately minimal:

• Node 18 built-ins only — zero npm dependencies, no package.json, nothing to build
• A vanilla JS card in a shadow root, injected into your existing dev page so it doesn't collide with your app's own styles or DOM
• A 127.0.0.1 sidecar server that serves the switcher card and swaps files on disk, using server-sent events (SSE) for live state so the card updates the instant a new variant lands
• SKILL.md and AGENTS.md as the agent contracts — the same instruction-file pattern used across Claude Code, Codex CLI, opencode, and (per the skill's own frontmatter) Cursor and "anything with a shell"
• Three shell smoke suites as the entire test harness — no test framework, matching the zero-dependency philosophy

The unit of work is what Variate calls a set: one target file plus N alternatives, stored in a .variate/<set>/ directory. 1.ext is always the user's original file, untouched. 2.ext through N.ext are the agent's fresh takes, and plan.json records what each position changed and what it costs. Which variant is currently "live" — meaning it's the one actually copied over the real target file — is derived by hashing on demand rather than stored, specifically so it can't silently drift out of sync with what's on disk.

The CLI surface

Every Variate command takes --root <project> explicitly, because — as the skill's own docs note — many agent harnesses reset the working directory between tool calls, so relying on an inherited cwd is fragile:

node <skill>/variate.mjs up    --root <project>              # card appears on the page
node <skill>/variate.mjs add   <file> [--n 4] [--new]         # register a set
node <skill>/variate.mjs check <set>                          # lint plan.json before presenting
node <skill>/variate.mjs use   <set> <n>                      # put one variant live
node <skill>/variate.mjs status                               # every set + which position is live
node <skill>/variate.mjs peek                                 # is anything queued? counts only
node <skill>/variate.mjs narrow <set> [<n>]                   # keep one, drop the rest, redraw
node <skill>/variate.mjs await [--timeout 20]                 # block briefly for the card's next ask
node <skill>/variate.mjs drain [--ack <id> --note "..."]      # claim every queued ask now
node <skill>/variate.mjs end   [<set>]                        # keep what's live, clean up

Exit codes double as signals the agent is meant to read programmatically: 0 for done, 1 for error, 2 for nothing to do, and 3 for "the user has to act" — which up returns when a sandbox blocks the injected card, since everything else still works and the user just needs to reload.

The rules Variate holds agents to

The skill's SKILL.md lays out what it calls a "critical floor" — eleven rules the agent is expected to obey even if it reads nothing else in the file. A few are worth calling out because they show the design philosophy more than any feature list would:

1. Variant 1 is sacred. The user's original file is never edited, deleted, or overwritten — every new idea is a numbered sibling.
2. Every variant is a drop-in replacement. Same exports, same props, same imports the app relies on. It has to actually run, not just look right in isolation.
3. No new dependencies, no invented design tokens. Variants must speak the project's own language — its existing utility classes, its existing components, its real copy. A variant that reaches for a new library "has already failed," per the skill's own wording.
4. Four positions that genuinely disagree. The skill explicitly warns that four minor tweaks to the same card grid is "wallpaper, not a round" — each variant has to change something structurally different.
5. A round narrows, it never accumulates. Once you pick a favorite, variate narrow retires the rest so future rounds build from a live decision instead of re-litigating rejected options.
6. The user's own hand-edits are sacred. If you edit the live file directly mid-session, Variate treats that edit as a new variant on the next switch — it never silently discards manual changes.

That last rule matters in practice: it means Variate is safe to use in the middle of a real editing session, not just at the start of a fresh component.

Setting it up

Variate installs the same way any agent skill does — dropped into your agent's skills directory and picked up automatically when your request matches its trigger description ("design variations," "try a different hero," "compare a few takes on this"). The project's homepage at variate-skill.vercel.app walks through the install for each supported harness. Once installed, a typical round looks like this in chat:

"Give me a few directions for the pricing page hero"

The agent resolves the target file (reading your existing tokens, imports, and surrounding sections first — the skill explicitly says to read the substrate before drafting), writes plan.json describing what each of the four positions will try, drafts the variants, and lands them one at a time so the card's pager grows as each file finishes. You flip through them with the arrow keys on your own running dev server and either keep one, ask for a refinement, or say you're done — no context switch to a separate tool required.

How this fits the wider agent-skill toolchain

Variate is narrow by design — it explicitly says it's not for "a single change with one right answer, a refactor, or a non-visual edit." That's a useful contrast with adjacent tools in the same space:

If you're building or evaluating skills of your own, explainx.ai's guide on how to build your first agent skill covers the same SKILL.md contract Variate relies on, and the agent skills into loops guide is relevant if you want a Variate-style round to trigger automatically rather than only on request — Variate's own SKILL.md already ships a Stop hook that waits on the card's next ask before ending the agent's turn, which is effectively a small loop.

What people will actually ask before adopting it

Does it lock me into a specific stack? No — the skill explicitly reads and reuses your project's existing tokens, components, and utility classes rather than assuming Tailwind, a specific framework, or a design system. Rule 3 of the critical floor exists specifically to prevent an agent from importing something new just to make a variant look different.

What if I'm starting from a truly empty project? Variate still works — up scaffolds an index.html, and add index.html --new --n 4 gives you four fresh takes on a blank page, going from a one-line brief to four live directions on a URL. The skill is explicit that it won't scaffold a full framework unprompted in that case.

Is there a hosted version I don't have to install? No — Variate's entire premise is that it runs against your localhost, not a hosted preview. The variate-skill.vercel.app site is documentation and marketing, not a hosted instance of the tool itself.

How mature is the project? As of August 20, 2026, the repo shows active recent commits, roughly 92 GitHub stars, 5 forks, and dedicated evals/, fixtures/, and references/ directories alongside the core skill — signs of a maintained tool rather than a weekend proof of concept, though it's still young (first commit July 17, 2026) and worth watching for breaking changes given the metadata.version: "3.2.0" already logged in its own SKILL.md.

Related reading

• What are agent skills? A complete guide for Claude Code, Cursor & MCP
• How to build your first agent skill, step by step
• How to turn your agent skills into loops
• DESIGN.md templates: the professional UI blueprint for AI agents
• DESIGN.md: the open spec for AI design systems
• Claude Design: Anthropic's design canvas
• Top 10 AI agent skills directories
• Official repo: github.com/Nutlope/variate · variate-skill.vercel.app

Repository stats, version numbers, and setup details in this post reflect the state of github.com/Nutlope/variate as of August 21, 2026. Check the repo directly for the latest release before installing.