figlens

<p align="center"> <img src="https://raw.githubusercontent.com/runkids/figlens/v0.10.1/assets/logo.png" alt="figlens" width="220"> </p> <h1 align="center">Give your coding agent the design details<br>to build, compare and follow changes.</h1> <p align="center"> <a href="README.md">English</a> · <a href="README-de.md">Deutsch</a> · <a href="README-es.md">Español</a> · <a href="README-fr.md">Français</a> · <a href="README-ja.md">日本語</a> · <a href="README-ko.md">한국어</a> · <a href="README-pt-BR.md">Português</a> · <a href="README-zh-CN.md">简体中文</a> · <a href="README-zh-TW.md">繁體中文</a> </p> <p align="center"> <a href="https://figlens.runkids.cc/"><img src="https://img.shields.io/badge/website-figlens.runkids.cc-8b78c8" alt="figlens website"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-8b78c8" alt="MIT license"></a> <a href="https://github.com/runkids/figlens/releases"><img src="https://img.shields.io/github/downloads/runkids/figlens/total?label=GitHub%20downloads&amp;color=79b9a5" alt="Total GitHub release asset downloads"></a> <a href="https://pi.dev/packages/@runkids/figlens"><img src="https://img.shields.io/badge/Pi-package-8b78c8" alt="Pi package"></a> <a href="#setup-opencode"><img src="https://img.shields.io/badge/OpenCode-V2-8b78c8" alt="OpenCode V2 plugin"></a> <a href="#setup-omp"><img src="https://img.shields.io/badge/OMP-plugin-79b9a5" alt="OMP plugin"></a> <a href="#mcp-and-skill"><img src="https://img.shields.io/badge/agents-CLI_%2B_MCP-79b9a5" alt="CLI and MCP for AI agents"></a> </p> <p align="center"> <a href="#start">Start</a> · <a href="#demo">Demo</a> · <a href="#why">Why</a> · <a href="#bundle">What the agent gets</a> · <a href="#pi">Pi</a> · <a href="#limitations">Limitations</a> · <a href="https://figlens.runkids.cc/docs/"><b>Docs</b></a> </p>

figlens turns saved Figma files into design context your coding agent can act on—not just a screenshot to interpret.

• Build from the source details. Read layout, text, styles, variables, Dev Mode annotations and Ready for dev status; export vector icons as SVG and images as assets. bundle collects a frame's data, assets and reference render; verify reports missing files, font checks and handoff limitations. MCP nodes can save large node JSON to a file with out instead of returning it inline.
• Compare the running UI. compare-image compares your screenshot with figlens's render and names the layers under differing regions. Review those differences and rendering warnings; it is not a pixel-perfect guarantee.
• Follow design changes. diff compares saved revisions; changes and watch report updates to tracked local scopes; freshness tells when a saved copy is older than the online file, and pull saves a new copy through your own browser sign-in. Save a new .fig from Figma to pick up design edits—this is not live Figma sync. Named accounts route each design to separate browser profiles and API-token environment variables; existing defaults stay unchanged. figlens sources init [DIR]: Scan local .fig files into .figlens/sources.json without overwriting it; names come from meta.json or the filename. Fill in the blank URLs before pulling.

Offline at the foundation. In Figma, File > Save local copy. Put design.fig next to your code. Then a Figma link is enough: its node id picks the frame. With no saved copy, copy the layers in Figma (right-click > Copy) and run figlens clipboard screen.fig; a copy has no images or vector outlines (how). One native binary reads it locally, without a running Figma app, login or network calls to Figma; only the opt-in freshness check (with a configured API token; default: FIGMA_TOKEN) and pull (through your browser sign-in) reach Figma.

<a id="start"></a>

Get started

No design file yet? Check your setup with the tiny public example: verify your chosen binary, find one frame and validate its bundle. No model required.

Put design.fig in your project, then choose one setup. Each gives your agent the figlens tools and the same built-in guidance for planning, implementation and image preparation.

| Setup | Use it for | Guidance comes from | |---|---|---| | Plugin | Claude Code, Codex, Antigravity, Cursor, Kimi Code | the plugin's skill and the server's workflow tool | | MCP | Claude Code, Cursor, Codex, Gemini CLI and other MCP clients | the server's workflow tool | | Pi | Pi 1.3.0+ | the package, which ships the skill | | OpenCode V2 | OpenCode V2 2.2.0 | the package skill | | OMP | OMP 18.13.2 | the package skill | | Herdr | a panel beside your agents in Herdr 0.1.12+: find a screen, hand it to one, track each screen's progress on a board | the receiving agent's own setup | | CLI | agents that only run shell commands, scripts and CI, or you | figlens workflow <topic>, or the optional skill |

Ordinary vs advanced. Ordinary use needs no setup: figlens search design.fig "query" reads the .fig and creates nothing. An optional local index is created only when you ask for one (figlens index prepare design.fig --scope 0:0), then reused across restarts and hosts. See Ordinary search and the optional local index. Optional and experimental: --mode semantic or hybrid ranks by meaning with a local model you set up yourself; see Optional semantic search.

<a id="setup-plugin"></a>

Plugin

One install adds the figlens skill and MCP server to your agent (Node.js 18+). The server is pinned to the plugin's release (npx -y @runkids/figlens@<version> mcp); update the plugin to move to a new version.

| Host | Install | |---|---| | Claude Code | claude plugin marketplace add runkids/figlens, claude plugin install figlens@figlens | | Codex | codex plugin marketplace add runkids/figlens, codex plugin add figlens@figlens | | Antigravity | agy plugin install https://github.com/runkids/figlens/tree/main | | Cursor | git clone --depth 1 https://github.com/runkids/figlens ~/.cursor/plugins/local/figlens, then reload the window | | Kimi Code | /plugins install https://github.com/runkids/figlens/tree/main in a session, then /reload |

skillshare installs the same plugin on several hosts at once: skillshare plugin add https://github.com/runkids/figlens.git --target claude --target codex --target cursor -g; update it later with skillshare plugin update figlens -g.

Restart the host or start a new session, then check that the figlens tools are listed. A plugin install copies the repository: about 7 MB, plus the Git history (about 60 MB) in Codex. Antigravity loads only the first 24 KB of the skill; the server's workflow tool serves the full guidance. Muse is not supported yet. Host matrix and what was verified

<a id="setup-mcp"></a>

MCP

Claude Code (Node.js 18+, macOS/Linux):

claude mcp add --transport stdio --scope local figlens -- npx -y @runkids/figlens mcp

Codex CLI (Node.js 18+, macOS/Linux):

codex mcp add figlens -- npx -y @runkids/figlens mcp

Any MCP client:

{
  "mcpServers": {
    "figlens": {
      "command": "npx",
      "args": ["-y", "@runkids/figlens", "mcp"]
    }
  }
}

Without Node.js, install the standalone binary (CLI) and use "command": "figlens", "args": ["mcp"]. Start a new session and check that the figlens tools are listed (/mcp in Claude Code). No separate skill install is required. Add --root <dir> after mcp to limit which folders figlens may read and write.

<a id="mcp-args"></a>

MCP startup arguments

Add these options after mcp in your client's args. These are the only MCP startup options; both are optional and repeatable.

| Option | Meaning | |---|---| | --root DIR | Allows design reads and exports inside DIR and its subfolders. Without it, figlens adds no path restriction: OS permissions still apply. It does not default to the current project or scan the computer. | | --storage-root DIR | Allows explicitly requested custom index storage inside DIR and its subfolders. It does not select or change the default storage location. |

Use absolute paths to existing directories. Each option and path is a separate array item; repeat the option for multiple folders. --root means a path boundary, not administrator access, and only restricts figlens MCP, not the agent's other tools.

Example with two design/output roots and two allowed storage roots:

{
  "mcpServers": {
    "figlens": {
      "command": "npx",
      "args": [
        "-y", "@runkids/figlens", "mcp",
        "--root", "/absolute/designs",
        "--root", "/absolute/project",
        "--storage-root", "/absolute/storage-a",
        "--storage-root", "/absolute/storage-b"
      ]
    }
  }
}

There is no figlens mcp --storage option. Choose the actual location with the index tool's storage argument (an absolute path under an allowed storage root), or CLI figlens index prepare design.fig --storage /absolute/storage-a. After prepare, figlens remembers that workspace's location and reuses it across restarts and hosts without repeating storage or --storage-root. Without a custom location, the per-user defaults apply; no storage flag is needed.

To keep these paths out of a checked-in config, or to share designs across Git worktrees, see roots in a checked-in config.

Multiple storage roots only expand the allowed locations: each storage argument still selects one location. They do not distribute, sync or back up indexes. An existing workspace database cannot be moved by simply naming another root; figlens refuses the conflicting location.

<a id="setup-pi"></a>

Pi

One package ships the CLI, MCP, viewer, /figlens commands and skill:

pi install npm:@runkids/figlens

Pi extension guide

<a id="setup-opencode"></a>

OpenCode V2

Install the package in OpenCode V2:

opencode plugin add @runkids/figlens

Restart the host, then run /figlens help. OpenCode V2

<a id="setup-omp"></a>

OMP

Install the same package in OMP:

omp plugin install @runkids/figlens

Restart the host, then run /figlens help. OMP

<a id="setup-cli"></a>

CLI

Run it through npm, or install the standalone binary:

npx @runkids/figlens --help                                                                # Node.js 18+, no install
curl -fsSL https://raw.githubusercontent.com/runkids/figlens/main/scripts/install.sh | sh  # macOS, Linux
brew install runkids/tap/figlens                                                           # Homebrew
irm https://raw.githubusercontent.com/runkids/figlens/main/scripts/install.ps1 | iex      # Windows PowerShell

npx runs the binary of the package version it resolves. Script installs update with figlens update; Homebrew installs with brew upgrade figlens. Binaries cover macOS (Apple silicon, Intel), Linux (arm64, x86_64) and Windows (x86_64).

An agent that uses the CLI reads its guidance with figlens workflow build (also audit, images, search, plan, planning-details and the opt-in yolo), which always matches the binary's version, or from the agent skill.

CLI reference

Different Figma accounts can use figlens pull --login --account work and optional "account": "work" in the source mapping. Existing default sessions need no migration. Figma accounts: browser login and API tokens.

figlens sources init [DIR]: Scan local .fig files into .figlens/sources.json