DESIGN:OS Figma Plugin & CLI (design-os-figma-plugin)

Zero-cost live Figma canvas bridge (figma-agent CLI + DESIGN:OS Bridge plugin) for AI coding agents — works on Figma Free.

Inspect live selections, scan design systems, create frames, bind variables, mutate auto-layout traits, and export visual verification PNGs directly from Claude Code, Codex, Gemini CLI, and Antigravity.

Quickstart · What it makes · Install · How it works · Commands · Limits

---

Why this exists

Figma’s official MCP server is remote and plan-gated: write tools need a Professional or higher plan and edit access, and read calls are capped on lower tiers (see Figma’s MCP rate limits). Large node dumps can also fill an agent’s context window. This bridge is a local alternative for the file you already have open in Figma Desktop, and it coexists with the official server. design-os-figma-plugin pairs a local WebSocket relay with typed CLI commands (inspect, scan-design-system, create-frame, set-text, export-png --assert) that work on Figma Free.

---

Quickstart

1. Install the plugin or CLI

In Claude Code:

/plugin marketplace add jangtrinh/design-os-figma-plugin
/plugin install design-os-figma-plugin@design-os-figma-plugin

Or from your terminal (Codex, Gemini CLI, Antigravity, OpenCode, or standalone CLI):

git clone https://github.com/jangtrinh/design-os-figma-plugin.git
cd design-os-figma-plugin
npm ci && npm run build          # Node.js 22; builds cli/dist/figma-agent.js and plugin/code.js
node cli/dist/figma-agent.js status --peek

Then, in Figma Desktop: Plugins → Development → Import plugin from manifest… and pick plugin/manifest.json. Full steps: Use with Claude Code, Cursor and Codex.

2. Ask in plain English

Open your project in your AI coding agent and describe what you need:

“Inspect the currently selected Figma frame, extract its auto-layout and variable tokens, and build the matching React component.”

“Scan the active Figma file’s design system tokens and create a new 1440x900 pricing section frame using our DLS components.”

“Update the copy and spacing on the selected hero frame in Figma and export a 2x PNG snapshot to verify visual parity.”

3. Verify your setup

python3 scripts/self_check.py

---

Use with Claude Code, Cursor and Codex

The bridge has two parts: a plugin that runs inside Figma Desktop, and the figma-agent CLI that your agent runs in a shell. The CLI talks to the plugin over a local WebSocket on 127.0.0.1 (ports 9410 to 9419). No model runs inside the bridge, and you bring your own agent.

Set up once (any agent)

git clone https://github.com/jangtrinh/design-os-figma-plugin.git
cd design-os-figma-plugin
npm ci && npm run build

In Figma Desktop: Plugins → Development → Import plugin from manifest…, then choose plugin/manifest.json. Open the plugin in a scratch file first.

Check the connection from the repository root:

node "$PWD/cli/dist/figma-agent.js" status --wait --timeout 60

Claude Code

/plugin marketplace add jangtrinh/design-os-figma-plugin
/plugin install design-os-figma-plugin@design-os-figma-plugin

Or write the skill from your built CLI: node cli/dist/figma-agent.js install-skill --folder ~/.claude/skills --with-craft --yes.

Cursor

Cursor loads skills from ~/.cursor/skills/ and ~/.agents/skills/ (Cursor docs).

node cli/dist/figma-agent.js install-skill --folder ~/.cursor/skills --with-craft --yes

Then ask in Agent chat: “Inspect my current Figma selection with the design-os-figma-agent skill.”

Codex

Codex scans ~/.agents/skills/ for user skills (Codex skills docs).

node cli/dist/figma-agent.js install-skill --folder ~/.agents/skills --with-craft --yes

Without a skills folder, tell any shell agent to run node "$PWD/cli/dist/figma-agent.js" status and then read its command list.

FAQ

Does it replace Figma’s official MCP server? No. They coexist. The official server is the better tool for Code Connect, cross-library search and working with Figma Desktop closed. This bridge reads and writes the open file through the Public Plugin API.

Does it need a paid Figma seat? No seat or access token for the bridge. It needs edit access to the file for writes, and Figma Desktop running the imported plugin.

Is it on Figma Community? No. It is a development plugin imported from this repository.

Does it run or pay for a model? No. You choose and pay for your own agent or provider.

Can the agent undo its own work? Yes. Each typed mutation seals its own undo step, so ⌘Z rolls back one change.

What licence is it under? It is source-available under PolyForm Shield 1.0.0: free to use and modify, but you may not resell it or build a competing product from it.

---

What it makes

Every deliverable produced by design-os-figma-plugin is backed by a deterministic verification gate rather than freehand AI guesswork.

Prompt: “Inspect the currently selected Figma frame, extract its auto-layout and variable tokens, and build the matching React component.”

---

Installation

Choose the setup that matches your AI coding agent. Every option installs the same canonical skill (skills/design-os-figma-craft/SKILL.md) and /doctor diagnostic suite.

Claude Code

Run these two commands inside Claude Code:

/plugin marketplace add jangtrinh/design-os-figma-plugin
/plugin install design-os-figma-plugin@design-os-figma-plugin

OpenAI Codex

Install to your personal Codex skills directory:

git clone https://github.com/jangtrinh/design-os-figma-plugin.git /tmp/design-os-figma-plugin
mkdir -p ~/.codex/skills/design-os-figma-craft ~/.codex/prompts
cp -R /tmp/design-os-figma-plugin/skills/design-os-figma-craft/* ~/.codex/skills/design-os-figma-craft/
cp /tmp/design-os-figma-plugin/prompts/doctor.md ~/.codex/prompts/design-os-figma-craft-doctor.md
rm -rf /tmp/design-os-figma-plugin

Gemini CLI & Google Antigravity

git clone https://github.com/jangtrinh/design-os-figma-plugin.git /tmp/design-os-figma-plugin
mkdir -p ~/.gemini/skills/design-os-figma-craft
cp -R /tmp/design-os-figma-plugin/skills/design-os-figma-craft/* ~/.gemini/skills/design-os-figma-craft/
rm -rf /tmp/design-os-figma-plugin

OpenCode, Cursor, Windsurf & Other Agent Harnesses

git clone https://github.com/jangtrinh/design-os-figma-plugin.git /tmp/design-os-figma-plugin
mkdir -p ~/.agents/skills/design-os-figma-craft
cp -R /tmp/design-os-figma-plugin/skills/design-os-figma-craft/* ~/.agents/skills/design-os-figma-craft/
rm -rf /tmp/design-os-figma-plugin

---

Usage & Prompt Cookbook

Once installed, skills/design-os-figma-craft/SKILL.md activates automatically when your prompt matches its domain triggers. Browse docs/cookbook.md for copy-paste prompt recipes.

Generate & Scaffold

"Inspect the currently selected Figma frame, extract its auto-layout and variable tokens, and build the matching React component."

Audit & Verify

"Scan the active Figma file's design system tokens and create a new 1440x900 pricing section frame using our DLS components."

Export & Automate

"Update the copy and spacing on the selected hero frame in Figma and export a 2x PNG snapshot to verify visual parity."

---

Commands & Diagnostics

---

How it works

1. Intent Routing — Your AI agent matches your request against skills/design-os-figma-craft/SKILL.md frontmatter triggers.
2. Progressive Context Loading — Only the entry-point SKILL.md router loads initially; detailed recipes and scripts load on demand.
3. Deterministic Execution — Domain scripts and contracts execute locally with reproducible inputs and outputs.
4. Gate Verification — scripts/self_check.py and domain verifiers (node cli/dist/figma-agent.js status --peek) validate the artifact before completion.
5. Zero-Telemetry Delivery — Verified files are written directly to your workspace with zero external network calls.

User Prompt / CLI Invocation
            │
            ▼
┌───────────────────────────────────────────────┐
│ skills/design-os-figma-craft/SKILL.md
│ Progressive disclosure router & hard rules    │
└───────────┬───────────────────────────────────┘
            │ loads on demand
            ▼
┌───────────────────────────────────────────────┐
│ node cli/dist/figma-agent.js status --peek
│ Deterministic build & contract enforcement    │
└───────────┬───────────────────────────────────┘
            │ verifies
            ▼
┌───────────────────────────────────────────────┐
│ python3 scripts/self_check.py + /doctor       │
│ Zero-telemetry local verification gate        │
└───────────────────────────────────────────────┘

What loads when

design-os-figma-plugin uses progressive context disclosure so your agent’s context window stays fast and focused:

---

File structure

design-os-figma-plugin/
├── .claude-plugin/
│   ├── plugin.json                 # Claude Code plugin manifest
│   └── marketplace.json            # Claude Code marketplace catalog
├── .codex-plugin/
│   └── plugin.json                 # OpenAI Codex plugin & interface manifest
├── .agents/
│   └── plugins/marketplace.json    # Cross-agent local plugin registry
├── .factory-plugin/
│   ├── plugin.json                 # Factory / Droid plugin manifest
│   └── marketplace.json            # Factory marketplace metadata
├── skills/
│   └── design-os-figma-craft/
│       └── SKILL.md                # Canonical agent skill entrypoint
├── commands/
│   └── doctor.md                   # /doctor diagnostic slash command
├── prompts/
│   └── doctor.md                   # Codex diagnostic prompt mirror
├── scripts/
│   └── self_check.py               # Deterministic repository & skill self-check
├── docs/
│   ├── cookbook.md                 # Copy-paste prompt recipes by job
│   └── llms.txt                    # GEO / LLM discovery index
├── PRIVACY.md                      # Zero-telemetry & local-first privacy commitment
├── SECURITY.md                     # Vulnerability disclosure & security policy
├── CONTRIBUTING.md                 # Contribution workflow & verification rules
├── CODE_OF_CONDUCT.md              # Contributor Covenant code of conduct
├── CHANGELOG.md                    # Release history
├── llms.txt                        # Root LLM indexing manifest
├── LICENSE                         # PolyForm Shield 1.0.0
└── README.md

---

Quality bar & Limitations

It’s working if…

• python3 scripts/self_check.py prints ok: design-os-figma-plugin self-check passed (design-os-figma-craft) and exits 0.
• node cli/dist/figma-agent.js status --peek passes with zero contract or test regressions.
• Your AI coding agent loads skills/design-os-figma-craft/SKILL.md automatically when given any prompt from docs/cookbook.md.
• Network traffic during execution remains zero (guaranteed by PRIVACY.md).

When not to use

• Headless CI servers where the Figma Desktop or browser app is not open with the plugin connected.
• Converting arbitrary live HTML pages via third-party html-to-figma scrapers (use screenshot image fills or native typed frame builders instead).
• Editing vector mesh illustrations better suited for design-os-svg-animation or design-os-3d-blender.

---

Watch

DESIGN:OS Bridge is free and source-available (PolyForm Shield). One episode of the Autonomous Design Agent series from the design:os by Jang channel (Vietnamese, with English terms):

Watch Autonomous Design Agent Ep. 5: Two-way bridge: One Comment, the AI Fixes Design and Code (2:44) for how one review comment can drive changes to both the design file and the code through the DESIGN:OS Bridge plugin and CLI.

More episodes: Autonomous Design Agent playlist.

---

DESIGN:OS Ecosystem

design-os-figma-plugin is one of the 13 source-available engines in the DESIGN:OS ecosystem:

---

Contributing, Governance & License

• Contributing: See CONTRIBUTING.md for pull request guidelines and verification gates (python3 scripts/self_check.py).
• Code of Conduct: Governed by CODE_OF_CONDUCT.md.
• Security & Privacy: Zero telemetry — see SECURITY.md and PRIVACY.md.
• Changelog & LLM Index: Track releases in CHANGELOG.md and machine-readable index in llms.txt.
• License: PolyForm Shield 1.0.0 © Jang Trinh. Free to use and modify, including for paid client work; you may not resell it or build a competing product from it.

---

If design-os-figma-plugin saves you time, a star on GitHub helps other engineers and AI agents find it.