d2fd6db141
* feat(core): add visual diff and patch apply tools diff_visual renders two nodes at one scale through the existing raster export, compares them with pixelmatch, and returns the diff PNG with the changed ratio and region in source-node coordinates. It takes export_image's scale and maxEdge inputs. FigmaAPI gains a CanvasKit-backed raster codec and a pageId export option, so the app and headless CLI decode pixels and render nodes off the current page. diff_apply applies diff_create and diff_show patches through the Figma API, validates every node before changing any, and supports dryRun and force. diff_show now simulates changes on a detached copy with the same property code. One serializer and parser back all three. diffDocuments compares two documents page by page by name path. Image tool results now reach models as media with their metadata as text, for any tool rather than export_image alone. diff_create, diff_jsx, and diff_visual join the default AI tool set, and the diff tools are no longer hidden from WebMCP. * feat(ai): show what each AI edit changed in its tool call Reviewing an AI run meant reading tool output or undoing steps to see what moved. Each document-changing call now rebuilds its page before and after from snapshots taken around it, and diffs each top-level layer's JSX with jsdiff, the same patch diff_jsx returns, to find the layers it changed. After the call returns, the changed region renders in both states at one size and pixelmatch highlights the difference. The tool card opens on a Changes view with a before/after slider, the pixel highlight, and a CodeMirror merge view of the JSX. Records are saved with the conversation next to attachments. Calls snapshot their page individually instead of through one shared variable, so concurrent calls in a step no longer overwrite each other's undo state. Core gains graphFromPageSnapshot for rebuilding a past page state, diffPageLayersJSX and jsxPatch (now shared with diff_jsx), renderRegionToImage for rendering two states of one region pixel for pixel, and comparePNGs on the raster codec. Settings > Chat > Change previews sets the stored image size or turns images off. * feat(cli): add diff commands and agent diff guidance openpencil diff create, jsx, show, apply, and visual run the Core diff tools on a file or the running app; apply writes back with --write or --output like eval. diff files compares two documents page by page and exits 1 when they differ. The chat prompt asks the agent to edit in place and to verify risky edits against a reference copy with diff_jsx, diff_create, and diff_visual. The skill, CLI reference, MCP tool table, and a new Comparing Designs page document the commands and tools. * feat(ai): render tool calls as summarized, highlighted cards Every tool call showed only a status and its output as a JSON string, so render calls hid their JSX, export_image dumped base64, and long runs filled the transcript with identical rows. A call now shows a one-line summary read from its input and chips that select and zoom to the layers it touched, switching to the run's page when needed. Expanded, it shows the JSX or script it wrote and its JSON input and output in a read-only CodeMirror view, and exported images inline. Render calls can be expanded while their input streams, so the JSX appears alongside the canvas preview. Consecutive calls beyond three fold into one row that keeps the latest call visible. CodeMirror loads with the first expanded call. The code theme gains a monospace fallback because the editor font variable is not always emitted. * feat(ai): let the chat AI diff its run against the starting state The diff tools compare two nodes, so checking an edit meant cloning a reference first, which the agent rarely did. diff_changes compares the current page, or one node under it, with the page as it was before the run first edited it, in diff_create's patch format. The app keeps that page snapshot per run and exposes it through FigmaAPI.changeBaseline; MCP and WebMCP have no run, so the tool is offered only to the AI chat, where it is enabled by default and the prompt asks for it before reporting. * feat(core): diff and patch node trees as JSX attributes diff_create, diff_show, diff_apply, and diffDocuments used a hand-rolled `key: value` property format that covered about fifteen properties, matched children by name path, and could not see moves. Nodes are now projected to the attributes the JSX export prints, and jsondiffpatch matches children (by ID or by name path) and detects moves. Patches list `-`/`+` attribute lines per node plus moved, added, and removed children. diff_apply checks every hunk first, applies attribute changes through the renderer's prop handling, and changes only the fields an attribute moves, so IDs, instance links, and other state survive. diff_show takes JSX attributes instead of a JSON props object. design-jsx gains sceneNodeAttributes, parseJSXAttributes, and jsxNodeFields for this, and the export round-trip property table is shared so every case is also diffed and applied. `diff files` loads its documents in order so node IDs, and so its patches, are deterministic. * feat(ai): report diff_changes as a patch diff_apply can replay diff_changes printed a unified diff of the JSX, which agents could read but not apply. It now diffs the run's baseline against the live page with the patch engine, matching nodes by ID, so a rename is a changed name and the output replays on the starting state with diff_apply. The chat's Changes view keeps the JSX line diff, which is for people. * fix(core): keep diff_apply atomic and diff files honest about differences - Added nodes render before anything else changes; if one fails, for example on a missing component, the rendered ones are deleted and nothing else is committed. - A hunk with an attribute the renderer ignores fails instead of reporting "unchanged". - diffDocuments reports `changed` from page statuses, and a page only one document has gets its status but no patch, since patches do not add or remove pages. diff files uses it, so an added empty page no longer reads as a match. - diff files rejects a --page neither document has and a --depth that is not a non-negative integer, exiting 2; diff_create's depth is validated the same way. * refactor(ai): drop the unused tool JSON slot and place the JSX summary comment * refactor(ai): find a tool change's clipping region with jsdiff clipChangedJSX scanned both JSX sources character by character for their common start and end. diffLines gives the unchanged lines before the first change and after the last; the app now declares the diff dependency Core already uses. |
||
|---|---|---|
| .claude | ||
| .devcontainer | ||
| .github | ||
| .storybook | ||
| .vscode | ||
| assets/brand | ||
| desktop | ||
| lint | ||
| packages | ||
| public | ||
| skills/open-pencil | ||
| src | ||
| tests | ||
| tools | ||
| vite | ||
| .coderabbit.yaml | ||
| .gitattributes | ||
| .gitignore | ||
| .gitleaks.toml | ||
| .lfsconfig | ||
| .oxfmtrc.json | ||
| AGENTS.md | ||
| bun.lock | ||
| bunfig.toml | ||
| CHANGELOG.md | ||
| commitlint.config.ts | ||
| CONTRIBUTING.md | ||
| index.html | ||
| knip.json | ||
| LICENSE | ||
| oxlint.json | ||
| package.json | ||
| playwright.config.ts | ||
| portless.json | ||
| README.md | ||
| SECURITY.md | ||
| steiger.config.ts | ||
| tsconfig.json | ||
| tsconfig.node.json | ||
| vite.config.ts | ||
| wdio.conf.ts | ||
OpenPencil
Open-source design editor. Opens .fig and .pen design files, includes built-in AI, and ships as a programmable toolkit with a headless Vue SDK for building custom editors.
Status: Active development. Usable today, with some rough edges as features evolve.
Try it online → · Download · Documentation · Roadmap · llms.txt
Installation
macOS (Homebrew):
brew install --cask openpencil
Or download from the releases page, or use the web app — no install needed.
Requires macOS 13 or later with current Safari updates, Windows 10 or later, or Linux with WebKitGTK 2.40+; the web app needs Chrome 111, Edge 111, Firefox 128, or Safari 16.4 or later. See system requirements.
What it does
- Opens
.figand.penfiles — read and write native Figma files, open supported Pencil documents from the app or OS file browser, copy & paste nodes between apps - AI builds designs — describe what you want in chat, 100+ tools create and modify nodes. Connect OpenRouter, Anthropic, OpenAI, Google AI, DeepSeek, Z.ai, MiniMax, or compatible endpoints
- Fully programmable — headless CLI, XPath queries, Figma Plugin API via
eval, MCP server for AI agents, and desktop agent integrations for Claude Code, Codex, and Gemini CLI - Lint, convert, and extract tokens — inspect documents, lint naming/layout/accessibility, convert between supported formats, analyze colors/typography/spacing/clusters, and extract design tokens
- Components and variants — create reusable components, group variants into component sets, insert local assets as instances, and switch variants from the inspector
- Image vectorization — convert image layers into editable vector layers with Recraft or fal.ai
- Design-to-code export — export selections as JSX/Tailwind, generate token outputs, and map designs into component-oriented code workflows
- Vue SDK for custom editors — headless components and composables for embedding OpenPencil into other apps or building workflow-specific editing surfaces. Read the SDK docs →
- Real-time collaboration — P2P via WebRTC, no server, no account. Cursors, presence, follow mode
- Auto layout & CSS Grid — flex and grid layout via Yoga WASM, with gap, padding, alignment, track sizing
- ~15 MB desktop app — Tauri v2 for macOS, Windows, Linux. Also runs in the browser as a PWA
CLI
npm install -g @open-pencil/cli
# or: bun add -g @open-pencil/cli
Inspect design files
Browse node trees, search by name or type, dig into properties — all without opening the editor:
openpencil tree design.fig
openpencil find design.pen --type TEXT
openpencil node design.fig --id 1:23
openpencil info design.fig
[0] [page] "Getting started" (0:46566)
[0] [section] "" (0:46567)
[0] [frame] "Body" (0:46568)
[0] [frame] "Introduction" (0:46569)
[0] [frame] "Introduction Card" (0:46570)
[0] [frame] "Guidance" (0:46571)
Query with XPath
Use XPath selectors to find nodes by type, attributes, and structure:
openpencil query design.fig "//FRAME" # All frames
openpencil query design.fig "//FRAME[@width < 300]" # Frames under 300px
openpencil query design.fig "//TEXT[contains(@name, 'Button')]" # Text with 'Button' in name
openpencil query design.fig "//*[@cornerRadius > 0]" # Rounded corners
openpencil query design.fig "//SECTION//TEXT" # Text inside sections
Export
Render to PNG, JPG, WEBP, SVG, PDF, PPTX, HTML, JSX, Storybook stories, or .fig — or export selections/pages as .fig and convert whole documents between supported formats:
openpencil export design.fig # PNG
openpencil export design.fig -f jpg -s 2 -q 90 # JPG at 2x, quality 90
openpencil export design.fig -f fig --page "Page 1" # Export a page as .fig
openpencil export design.fig -f jsx --style tailwind # Tailwind JSX
openpencil export design.fig -f html --css tailwind # Tailwind HTML fragment
openpencil export design.fig -f html --html standalone --assets external # HTML + assets
openpencil export design.fig -f storybook --framework vue # Storybook stories per component
openpencil convert design.pen output.fig # Convert between document formats
openpencil import page.html --css styles.css -o page.fig # HTML/CSS → editable .fig
DOM/CSS input flows through @open-pencil/dom-css, so HTML, authored CSS, and Tailwind utility CSS can become editable OpenPencil layers:
openpencil import card.html --css card.css -o card.fig
openpencil import card.html --tailwind "flex flex-col gap-3 w-80 p-6 rounded-xl bg-white" -o card.fig
<div className="flex flex-col gap-4 p-6 bg-white rounded-xl">
<p className="text-2xl font-bold text-[#1D1B20]">Card Title</p>
<p className="text-sm text-[#49454F]">Description text</p>
</div>
Lint design files
Catch naming, layout, structure, and accessibility issues from the terminal:
openpencil lint design.fig
openpencil lint design.pen --preset strict
openpencil lint design.fig --rule color-contrast
openpencil lint design.fig --list-rules
Analyze and extract design tokens
Audit an entire design system from the terminal — find inconsistencies, extract the real palette, and spot components waiting to be extracted:
openpencil analyze colors design.fig
openpencil analyze typography design.fig
openpencil analyze spacing design.fig
openpencil analyze clusters design.fig
openpencil analyze overlaps design.fig
openpencil variables design.fig
#1d1b20 ██████████████████████████████ 17155×
#49454f ██████████████████████████████ 9814×
#ffffff ██████████████████████████████ 8620×
#6750a4 ██████████████████████████████ 3967×
3771× frame "container" (100% match)
size: 40×40, structure: Frame > [Frame]
2982× instance "Checkboxes" (100% match)
size: 48×48, structure: Instance > [Frame]
Script with Figma Plugin API
eval gives you the full Figma Plugin API. Modify the file, write it back:
openpencil eval design.fig -c "figma.currentPage.children.length"
openpencil eval design.fig -c "figma.currentPage.selection.forEach(n => n.opacity = 0.5)" -w
Control the running app
When the desktop app is running, omit the file argument — the CLI connects via RPC and operates on the live canvas. Useful for automation scripts, CI pipelines, or AI agents that need to interact with the editor:
openpencil tree # Inspect the live document
openpencil export -f png # Screenshot the current canvas
openpencil eval -c "figma.currentPage.name" # Query the editor
All commands support --json for machine-readable output.
AI & MCP
Built-in chat
Press ⌘J (CtrlJ on Windows and Linux) to open the AI assistant. It has 100+ tools that can create shapes, set fills and strokes, manage auto-layout, work with components and variables, run boolean operations, analyze design tokens, and export assets. Bring your own API key for OpenRouter, Anthropic, OpenAI, Google AI, DeepSeek, Z.ai, MiniMax, or compatible endpoints. No backend, no account.
Not every provider works in the browser, and not every model streams tool calls correctly. See BYOK provider & model compatibility for measured results — contributions welcome.
Coding agents (desktop)
Use Claude Code, Codex, or Gemini CLI directly in the chat panel. The agent connects to the editor's MCP server and uses all 100+ design tools. Requires the desktop app and the agent CLI installed locally.
Pi is also available as an optional AI SDK Harness provider. Install its companion CLI with npm install -g @open-pencil/harness, then add a Pi model profile in Settings → AI & agents. The companion is installed separately so OpenPencil does not bundle a JavaScript runtime for users who do not enable Harness providers.
Setup (Claude Code):
- Install the ACP adapter:
npm install -g @agentclientprotocol/claude-agent-acp - Add MCP permission to
~/.claude/settings.json:{ "permissions": { "allow": ["mcp__open-pencil__*"] } } - Open the desktop app → ⌘J → select Claude Code from the provider dropdown
MCP server
Connect Claude Code, Cursor, Windsurf, or any MCP client to inspect, modify, and export design documents headlessly. 100+ tools. Full docs →
Stdio (Claude Code, Cursor, Windsurf):
npm install -g @open-pencil/mcp
claude mcp add --scope user open-pencil -- openpencil-mcp
For other MCP clients:
{
"mcpServers": {
"open-pencil": {
"command": "openpencil-mcp"
}
}
}
HTTP (scripts, CI):
openpencil-mcp-http # Unix socket on macOS/Linux + http://127.0.0.1:7600/mcp
Local clients discover the private Unix socket automatically and fall back to localhost TCP. Set PORT=0 to disable TCP on macOS/Linux.
File access: Set OPENPENCIL_MCP_ROOT to scope file operations (open_file, new_document, export path param) to a directory. Defaults to the current working directory.
AI agent skill
Teach your AI coding agent to use OpenPencil — inspect designs, export assets, analyze tokens, modify .fig files:
npx skills add open-pencil/open-pencil
Works with Claude Code, Cursor, Windsurf, Codex, and any agent that supports skills.
For documentation-aware agents, the docs site publishes llms.txt, llms-full.txt, and per-page Markdown files generated from the VitePress docs.
Collaboration
Share a link to co-edit in real time. No server, no account — peers connect directly via WebRTC.
- Click the share button in the top-right panel
- Share the generated link (
app.openpencil.dev/share/<room-id>) - Collaborators see your cursor, selection, and edits in real time
- Click a peer's avatar to follow their viewport
Why
Figma is a closed platform that actively fights programmatic access. Their MCP server is read-only. figma-use added full read/write automation via CDP — then Figma 126 killed CDP. Your design files are in a proprietary binary format that only their software can fully read. Your workflows break when they decide to ship a point release.
OpenPencil is the alternative: open source (MIT), reads .fig files natively, every operation is scriptable, and your data never leaves your machine.
See the roadmap for product direction and current Figma compatibility gaps.
Community
- Discord — chat, quick questions, and showing a problem live
- GitHub Discussions — Q&A for help, Ideas for feature proposals, Show and tell for what you built; maintainers post Announcements there
- Issues — reproducible bugs; report security problems through a private advisory
Contributing
bun install
bun run dev:portless # Web editor at https://open-pencil.localhost
bun run tauri dev # Desktop app (requires Rust)
CONTRIBUTING.md covers setup, quality gates, pull requests, and commits. AGENTS.md maps the repository and links the guide inside each package. Desktop builds need Rust and the Tauri v2 prerequisites; run bun run tauri build.
Tech stack
| Layer | Tech |
|---|---|
| Rendering | Skia (CanvasKit WASM) |
| Layout | Yoga WASM (flex + grid via fork) |
| UI | Vue 3, Reka UI, Tailwind CSS 4 |
| File format | Kiwi binary + Zstd + ZIP |
| Collaboration | Trystero (WebRTC P2P) + Yjs (CRDT) |
| Desktop | Tauri v2 |
| AI/MCP | Vercel AI SDK (multi-provider BYOK), MCP SDK, Hono |
Acknowledgments
Thanks to @sld0Ant (Anton Soldatov) for creating and maintaining the documentation site.
License
OpenPencil is licensed under the MIT License.
Copyright (c) 2026 Danila Poyarkov and OpenPencil contributors.