The best way to design with AI agents. Click anything in your running app, say what should
change, and your coding agent edits the exact line of code.

npx -y @cychien/ezdesign@latest http://localhost:5173 --agent claude

Works with Claude Code, Codex and Gemini CLI. Open source, runs on your machine, no API
key. See it in action at ezdesign.dev.

Why

Describing UI changes in chat is lossy. "Make the second card's title a bit bigger" leaves your
agent guessing which card, which file and how much. Designing in Figma first means building
everything twice.

ezdesign puts the review on the real page. You point, it tells the agent where that thing lives in
your source, and the change appears in place a moment later through your dev server's hot reload.

  you                          ezdesign                          your agent
  ───                          ────────                          ──────────
  click the hero title    ──▶  src/sections/Hero.tsx:13     ──▶  edits that line
  "make this 56px"             <Hero ← App>                      page hot-reloads

Quick start

You need Node.js 22.13+ and an app running locally.

1. Open a review from your project's root, pointing at the page you want to work on:

npx -y @cychien/ezdesign@latest http://localhost:5173/pricing --agent claude

A review shell opens in your browser with your app inside it and the agent beside it.

2. Point and comment. Press E and click an element, or R and drag over an area. Write what
should change. Repeat for as many things as you like.

3. Send with ⌘↵. The agent works through the batch, streams what it is doing, and the page
updates in place. Review, comment again, send again.

Or start it from your agent

Add the skill once:

npx skills add cychien/ezdesign --skill ezdesign

Then type /ezdesign in Claude Code, Codex or Gemini CLI, and the agent opens the review for you.

Exact file:line for Vite + React

ezdesign works with any framework, no code changes. For Vite + React, add the plugin and every
annotation carries the exact source line:

// vite.config.ts
import { ezdesignSource } from '@cychien/ezdesign/vite'

export default defineConfig({
  plugins: [ezdesignSource(), react()],
})

It only runs in dev (apply: 'serve') and never touches production builds.

Features

• Point, don't describe. Click an element, drag over a region, or select a run of text. Each
  annotation reaches the agent with its source file:line, React component chain, selector, text
  and viewport.
• Every screen size at once. Preview at phone, tablet or desktop, or lay them all out on one
  grid at true size, scrolling and navigating together.
• Explore before you commit. Ask for a few versions of any element and flip through them on the
  real page. Keep the one you like.
• Canvases beside your app. The agent draws whole design directions as real HTML pages at real
  widths, on a board next to your app. Pick one and it builds that into your components.
• A design library from the whole web. The Chrome extension saves any image, video or region
  of a page, with tags and a note. Pull those into a comment as references.
• The agent lives in the shell. Its replies, plan, tool calls, questions and permission
  prompts all show up next to your app. No terminal to babysit.
• Local-first. Your code never leaves your machine, and ezdesign uses the agent you already
  have, so there is nothing new to pay for.

Using the review shell

Annotating

Annotations queue up beside your app and stay editable until you send. Paste or drop a screenshot,
or any file, straight into a comment and the agent gets a path to it.

Commands in the comment box

Type / in a comment for these:

Type $ in the note box to run one of your installed agent skills over the batch.

Shortcuts

Choosing the agent and model

The pills above the note box pick the agent and the model, plus reasoning effort where the agent
offers it. Switching models keeps the conversation, so you can move to a stronger model for the
hard part of a review and back again. Switching agents starts a new conversation.

Agents

ezdesign talks to agents over the Agent Client Protocol. Any
other value is run as an ACP server command, so a custom agent works too:
--agent 'my-acp-agent --flag'.

Canvases

A canvas is an infinite board of frames. Each frame is a complete HTML page at a real viewport width,
so a 390 frame is a phone to its media queries however far you zoom out.

• Open one from the + in the tab strip, or run ezdesign without a url to work on canvases in
  a project that has no dev server yet:

  npx -y @cychien/ezdesign@latest --agent claude
  

• Ask for designs and the agent adds them as frames. Annotate a frame exactly like your app.
• Move around by dragging the background or scrolling. Pinch or ⌘-scroll to zoom, ⇧1 to fit
  everything, ⇧0 for 100%. Frames snap to each other, and ⌘Z undoes.
• Bring one into the app with /element: comment on your app, switch to the canvas, ⌘-click
  the frame you mean.

Canvases are saved in your project under .ezdesign/canvases/. Commit them or ignore them, your
call. Frames are served from a separate origin, so agent-written pages cannot reach the review shell.

Design library

The Chrome extension saves references into one library under ~/.ezdesign/library/, shared by
every project. Saving works anytime, with or without a review open.

npx -y @cychien/ezdesign@latest extension install

Then open chrome://extensions, turn on Developer mode, choose Load unpacked and pick
~/.ezdesign/extension. Works with Chrome, Chromium, Arc, Brave, Edge and Vivaldi on macOS and
Linux.

• Right-click any image or video and save it to ezdesign.
• Press Alt+Shift+S (or click the toolbar icon) and drag over any part of a page.
• Add tags and a note on why it is good, so the agent knows how to use it later.

ezdesign extension status checks the install, and ezdesign extension uninstall removes it while
keeping your library.

Sessions and updates

A review belongs to your project (the nearest .git or package.json), not to a port. Restart
your dev server on another port and run ezdesign again: the shell switches over and the
conversation and queue carry on.

Reviews survive restarts. The background daemon brings its sessions back on the ports they held,
your open shell reconnects on its own, and the agent resumes the conversation it was in.

When a newer version is out, a card at the top of the shell offers it. One click installs it and
hands your sessions over, and if the new version fails to start you stay on the one you had.
Always run the CLI as npx -y @cychien/ezdesign@latest; a bare npx @cychien/ezdesign keeps
using whatever version npx cached. Update the skill with npx skills update ezdesign.

CLI

ezdesign [<url>] --agent <name>   open or resume this project's review
ezdesign status                   show running sessions
ezdesign stop                     stop the background daemon
ezdesign extension install        set up the Chrome extension
ezdesign --help                   everything else

ezdesign here is short for npx -y @cychien/ezdesign@latest.

Configuration

Privacy

The daemon binds to 127.0.0.1 and your code stays on your machine. Apart from your agent's own
traffic, ezdesign reaches out only to npm, to fetch the agent adapter and to check for a newer
version (at most every four hours, off with EZDESIGN_NO_UPDATE_CHECK=1), and to the ezdesign
backend for sign-in and inspiration search when you use them.

Development

npm run dev                 # watch src/, serve the playground fixture, open a review with an agent
npm run dev -- --no-plugin  # the same, without the Vite plugin, to see fallback anchors
npm run dev:cli status      # the CLI, pointed at the dev daemon
npm run brand               # regenerate logo assets after editing src/brand.ts
npm run check               # build, typecheck, test

Dev mode keeps its state in .dev/, so your own ~/.ezdesign is never touched, and each checkout
picks its own ports, so worktrees run side by side. The review target is
fixtures/playground.

Status

Early and moving fast. Feedback and issues are welcome.

License

MIT