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 |
| 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.
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
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.
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.
Pi
One package ships the CLI, MCP, viewer, /figlens commands and skill:
pi install npm:@runkids/figlens
OpenCode V2
Install the package in OpenCode V2:
opencode plugin add @runkids/figlens
Restart the host, then run /figlens help. OpenCode V2
OMP
Install the same package in OMP:
omp plugin install @runkids/figlens
Restart the host, then run /figlens help. OMP
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.
Agent skill (optional)
The skill teaches an agent the same workflow as the built-in guidance: find the frame, read the bundle in small pieces, plan scoped work and check the running UI against the design. It holds instructions only, so pair it with the CLI or MCP. MCP and Pi setups do not need it.
Recommended: skillshare. Install the skill once and sync it to each agent you use:
skillshare install github.com/runkids/figlens/skills/figlens
skillshare sync
The same tool can also set up the figlens MCP connection for those agents:
skillshare mcp add figlens --global --target claude --target codex --target cursor --no-tui -- npx -y @runkids/figlens mcp
skillshare sync mcp --global
Other ways to install the skill:
npx skills add runkids/figlens --skill figlens # Skills CLI
Or copy skills/figlens/ from this repository or a release archive into your agent's skills directory (Claude Code: ~/.claude/skills/). An installed skill updates separately from the binary; figlens workflow always matches it.
Then ask for a screen:
Build the task board from ./design.fig in this project.
Find the matching frame, use this project's components and image workflow,
then compare the running UI with the design and fix confirmed differences.
Report missing assets and any checks you could not run.
The agent finds the frame, bundles its design data, assets and reference image, then builds the screen with your stack. The shared workflow guides font and asset checks; missing inputs are reported while layout implementation continues with documented fallbacks. Ask for the changed files and a browser comparison.
This page is built from README.md in the repository.