Framio quick start: design with Claude Code and Codex

Framio is a free, open-source design canvas for coding agents. Claude Code, Codex, or another agent writes React and Tailwind screens into your repository. Framio renders those files on a live canvas, where you can select elements, review mobile and desktop layouts, and pin feedback before implementing a design in your app.

Install

Framio runs on macOS on Apple Silicon and Linux on x64 or arm64. Intel Macs and Windows are not supported. The installer downloads a binary from Framio’s GitHub releases. No account or subscription is required.

Run this command in your terminal:

curl -fsSL https://framio.design/install.sh | sh

You can read the installer before running it. Adding registry components with framio add also requires Node.js.

Quick start

Open your project’s directory and run:

framio init
framio start

framio init creates .framio/ with React, Tailwind, shadcn/ui, and the agent skill. framio start prints local, network, and available Tailscale URLs. It opens your browser when a desktop session is available. Keep that terminal running. Press Ctrl+C when you want to stop it.

To run the canvas in the background instead:

framio start --background
framio status
framio stop

Remote machines and VMs

In v0.0.8, framio start listens on all IPv4 interfaces by default. SSH into the machine where your repository lives and start the canvas there:

cd your-project
framio start

Copy a printed network URL and open it in the browser on your main computer. If Tailscale is installed and running, Framio also prints its IP URL and its hostname when MagicDNS is enabled. Both computers must be able to reach that address. You do not need --host to enable network access.

SSH, CI, and headless Linux sessions skip automatic browser launch. No desktop browser or display is required on the VM. Live previews work without Chromium. Screenshots, thumbnails, and geometry inspection use Framio’s own headless Chromium and need its system libraries and sandbox support. If it is unavailable, the canvas stays running and reports the failed feature. Select a frame to view it live.

Clipboard actions also work over remote HTTP. Keep the SSH terminal open, or use framio start --background and manage it with framio status and framio stop.

For local-only access:

framio start --host 127.0.0.1

To bind a specific interface, use framio start --host <address>. Anyone who can reach the port can edit the canvas. Limit access with your firewall and Tailscale access rules. Tailscale encrypts HTTP traffic through its tunnel. HTTPS requires a separate setup, such as Tailscale Serve.

Updates

The canvas and CLI share update downloads, progress, and installation state. In the canvas, use the update control to download a release while you keep designing. Install when you are ready, then use Restart to update to switch the project to the installed version. A supervised restart retains the project’s listen address and port.

From the terminal:

framio upgrade --check
framio upgrade --download
framio upgrade --install

Downloads are checksum-verified before installation. CLI installation leaves running projects on their current version and prints which ones need a restart. Save your work, then run framio stop and framio start in each project. If you used a custom --host, pass the same address when starting again.

To restore the previous installed binary:

framio upgrade --rollback

Restart running projects to use the restored version. If a replacement server cannot start during a supervised restart, Framio attempts recovery with the previous executable and reports the result.

Binary updates do not change your project’s skills, dependencies, themes, or designs. If your older version does not have framio upgrade, rerun the install command above to get v0.0.8 or later.

Use Framio with Claude Code or Codex

framio init installs the design skill into .claude/skills for Claude Code and .agents/skills for Codex. An agent that reads either skill directory can follow the same workflow. Open or restart your coding-agent session after initializing the project so it can discover the installed skill.

Ask your agent:

Use Framio to design the onboarding for my invoicing app. Show desktop and mobile layouts. Ask me about the product before choosing a direction.

The agent gathers context, proposes visual directions, and creates each screen as a .tsx file. It screenshots and reviews the frame before continuing. Review the designs on the canvas, then ask for changes using selections or comments.

Framio provides the canvas and design workflow. You still use your own coding agent and its model provider. Framio does not include a model subscription.

Where designs live

Framio keeps design files in your repository. It does not implement them in your application automatically.

Commit the design files when you want to share or review them in a pull request. Use your repository’s normal review process for changes an agent makes.

DESIGN.md

Edit .framio/DESIGN.md to update the design system across frames. Its front matter defines tokens, and the canvas restyles designs when you save it.

---
colors:
  primary: "#0C64FF"
typography:
  body-md:
    fontFamily: Geist
    fontSize: 15px
rounded:
  lg: 14px
---

Frames use ordinary React and Tailwind. The bundled shadcn/ui components pick up tokens such as primary, background, and muted. Framio follows Google’s DESIGN.md format.

Comments and selections

Click a frame or a named layer to show your agent what you mean. Selection context includes the viewport width, so feedback can target the mobile layout specifically.

Press C or choose Comment, then click a frame to pin feedback. Enter saves the comment; Escape cancels it. Use the comments panel to reply, resolve, or reopen a thread.

Ask your agent:

Address the open Framio comments. Reply in each thread, verify the changed design, and resolve it when the fix is complete.

Comments and replies live in .framio/comments.json. The agent edits the design files, and the canvas updates live.

Responsive frames

A frame can render at several widths without duplicating its component:

export const meta = {
  name: "Invoices",
  widths: [1440, 768, 390],
  height: 900,
};

Framio shows the viewports side by side. Each width can be selected individually. To screenshot only the mobile viewport:

framio screenshot 11-invoices/list --width 390

Compare a design with your app

When you approve a design, ask your agent to implement it in your real app. Run your application, then compare it with the matching frame:

framio screenshot --url http://localhost:3000/invoices --compare 11-invoices/list --width 390

Replace the URL and frame path with your own. Framio captures the running page and places it next to the design at the same width. It saves the comparison under .framio/.state/screenshots/urls/. Review desktop and mobile separately, and ask the agent to iterate on visible differences.

Commands

Support and source

Framio is created by Harshit and released under the MIT license. The source repository includes the CLI, canvas, and contribution guidelines.

Report bugs in GitHub Issues. For a security issue, follow the private reporting instructions.