Framery

A local-first, agentic design board for solo developers.

You describe what to design. Your coding agent lays it out on a canvas: screens, flows, a design system, a plan. You look at it in the browser, think out loud, and ask for changes. Everything is plain files in your repo, there is no account, no cloud and no build step, and there are no dependencies to install.

Why

Solo developers design in their head, in a chat with an agent, or in a design tool the agent cannot touch. Framery gives the agent a board it can read and edit through tools, and gives you a Figma-like surface to review it.

• The agent edits, you review. Every screen is an HTML file. Placement, grouping, arrows and descriptions are tools your agent calls (MCP, HTTP or CLI). The browser is where you look, pan and zoom.

• Local-first. Your design lives in framery/ inside your project, next to your code, in git. Nothing leaves your machine.

• Safe to let an agent loose. Every prompt's changes are one entry in an undo trail: go back from the History panel, or tell the agent to undo.

• Made for agents to read, too. A flow is a small JSON file with descriptions for whoever builds the screen. outline prints a page as text in reading order, so an agent understands a flow without opening an image.

• Light. Plain Node, no dependencies. Previews are drawn by the Chrome or Edge you already have. The canvas draws only what is on screen.

Related MCP server: Sheet

What you get

Install

Requires Node 22 or newer. Previews, measured anchors and export use Chrome or Edge if one is installed; without it everything else still works.

In your project's root folder:

cd my-project
npm install --save-dev github:rafimaliki/framery#v0.6.0
npx framery init
npx framery

Then open http://127.0.0.1:4173 (if that port is busy, the studio takes the next free one and prints it).

init does four things, and is safe to run again:

1. Copies the framery skill into the folders of the agents you use, and only those (table below), so your agent already knows how to operate the board.

2. Registers the MCP server for them (existing entries are kept). Restart your agent once so it connects.

3. Adds the generated folders (.cache, exports, .history) to .gitignore.

4. Creates framery/<your-project>/ with an empty project, if there is none.

It prints what it wrote and which agents it skipped. It never writes a CLAUDE.md.

Choosing agents

npx framery init --agents claude,codex     # only these
npx framery init                           # no flag: the agents already in this folder or on your PATH, else claude

The choice is saved in framery/config.json, so a bare npx framery init repeats it and doctor checks those agents. The skill folders are generated copies: refresh them with init, do not edit them.

A design repo with no agent files in it

npx framery init --global --agents claude,codex

This puts the skill and the MCP server in your own home folder (~/.claude/skills and ~/.claude.json, ~/.agents/skills and ~/.codex/config.toml, ~/.omp/agent/skills) and leaves the repo alone. The server is npx framery mcp --data <absolute path>, so it does not depend on the repo's node_modules. omp has no user-level MCP file we know of: init prints the line to add by hand. Check it with npx framery doctor --global --agents claude. Put one line in the repo's AGENTS.md for the next person: the framery skill is installed per user, run npx framery init --global.

From then on, ask your agent: "Design the sign-in flow in framery", "connect these screens", "add a plan page and mark home as built", "undo that".

No MCP? The same tools run from a shell: npx framery cmd outline '{"page":"flows"}', and npx framery tools lists them all.

Updating

Nothing updates by itself, and framery never calls the network. Updating is a choice you make:

npx framery doctor                                        # what is installed, and is this project in step?
npm install --save-dev github:rafimaliki/framery#v0.6.0  # pick a release (see CHANGELOG.md, or the tags)
npx framery init                                          # refresh the skill and the MCP entry
npx framery doctor                                        # confirm

• Releases are git tags. Pin the one you want; the install line above is the whole upgrade. npm ls framery shows what you have.

• Restart a running studio after installing: it keeps running the version it started with. Cached previews are measured again once, by themselves; new files (comments, chat) appear only when first used.

• Your design is yours. An upgrade replaces the app in node_modules and, with init, the skill copy. It does not rewrite framery/. A release that changes the data format says so in the changelog and ships its migration; a project saved by a newer version than the one installed is refused with a clear message, never half-read.

• doctor exits non-zero when the skill or MCP entry is out of date or a project needs a newer version, so you can run it in CI or a hook.

Using it day to day

npx framery                  start the studio on http://127.0.0.1:4173 or the next free port (--port N: that port or fail; --no-render)
npx framery mcp              the stdio MCP server (registered for you by init)
npx framery init             wire a project; safe to repeat (--agents claude,codex,omp; --global for your home folder)
npx framery doctor           check versions and wiring (the chosen agents only)
npx framery watch            print each comment and chat message from the studio as it arrives (an agent runs this under its background monitor; --once prints what is waiting, then exits)
npx framery stop             end the studio (and a watcher) properly; safe when nothing runs
npx framery tools            every tool and what it does
npx framery cmd <tool> '{}'  run a tool from a shell
npx framery render           previews, anchor boxes, autoHeight heights

Edit anything on disk (an HTML frame, a CSS file, a page) and open pages update without a refresh. Frames are ordinary HTML, drawn at their own size with your project's CSS. Give an element id="…" or data-anchor="…" and an arrow can start or end on it.

The tools an agent gets

outline, get_page, add_item, update_item, rename_item, move_items, move_to_page, move_page, layout_flow, arrange, group_items, connect, check_arrows, check_design, batch, list_anchors, set_cell (and add_row, add_column, …), set_token, render_frames, export_item, link; components: create_component, update_component, use_component, promote_component, find_candidates, …; and history, checkpoint, undo, restore. The skill tells an agent which to reach for.

A project folder

my-project/
  framery/
    <project>/
      project.json     title, pages, tokens file, data format
      pages/<id>.json  items (frame, group, node, table) and arrows; a plan is a page with a table
      tokens.css       design tokens the frames use
      library.json     optional: components, with library/<id>.html (fragments with {{props}})
      *.html, *.css    your frames, any layout
      .cache/          previews and measurements (generated, safe to delete)
      exports/         files written by export_item
      .history/        the undo trail

A frame is an HTML file built from your own CSS. Edit pages through the tools, not by hand: they keep arrows valid and groups fitted. The data format and decisions behind it are in docs/design-studio.md.

Status

Early (0.x). Solid for one person designing with one agent. Not built for real-time collaboration, and the canvas is read-only by hand on purpose: placement comes from the agent. Node is the only supported runtime for now.

git clone https://github.com/rafimaliki/framery && cd framery
npm test          # node --test, no install step
npm run dev       # restart on change

License

MIT