시작하기 · figlens 문서

디자인 파일이 아직 없나요? 작은 공개 예제로 설정을 확인하세요: 사용할 바이너리, frame 검색, bundle 내용을 검증합니다. 모델은 필요하지 않습니다.

프로젝트에 design.fig를 놓고 아래 설정 중 하나를 고르세요. 어느 것을 골라도 에이전트가 figlens 도구와, 계획·구현·이미지 준비를 위한 같은 내장 가이드를 사용할 수 있습니다.

설정	대상	가이드 출처
플러그인	Claude Code, Codex, Antigravity, Cursor, Kimi Code	플러그인에 포함된 skill과 서버의 `workflow` 도구
MCP	Claude Code, Cursor, Codex, Gemini CLI 등 MCP 클라이언트	서버의 `workflow` 도구
Pi	Pi 1.3.0+	skill이 포함된 패키지
OpenCode V2	OpenCode V2 2.2.0	패키지에 포함된 skill
OMP	OMP 18.13.2	패키지에 포함된 skill
CLI	셸 명령만 실행하는 에이전트, 스크립트와 CI, 또는 직접 사용	`figlens workflow <topic>` 또는 선택 사항인 skill

일반 vs 고급. 일반 사용에는 설정이 필요 없습니다. figlens search design.fig "query"는 .fig를 읽을 뿐 아무것도 만들지 않습니다. 선택형 로컬 인덱스는 요청할 때만 만들어지며(figlens index prepare design.fig --scope 0:0) 이후 재시작과 호스트를 넘어 재사용됩니다. 일반 검색과 선택형 로컬 인덱스를 참고하세요. 선택 사항·실험적: --mode semantic 또는 hybrid는 직접 준비한 로컬 모델로 의미 기준 순위를 매깁니다. 선택형 시맨틱 검색을 참고하세요.

플러그인

한 번 설치하면 figlens skill과 MCP 서버가 에이전트에 추가됩니다(Node.js 18+). 서버는 플러그인 릴리스에 고정됩니다(npx -y @runkids/figlens@<version> mcp). 새 버전으로 바꾸려면 플러그인을 업데이트하세요.

호스트	설치
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` 후 창을 다시 로드
Kimi Code	세션에서 `/plugins install https://github.com/runkids/figlens/tree/main` 실행 후 `/reload`

skillshare로 같은 plugin을 여러 호스트에 한 번에 설치할 수 있습니다: skillshare plugin add https://github.com/runkids/figlens.git --target claude --target codex --target cursor -g; 이후 업데이트는 skillshare plugin update figlens -g.

호스트를 다시 시작하거나 새 세션을 열고 figlens 도구가 표시되는지 확인하세요. 플러그인 설치는 저장소를 복사합니다(약 7 MB, Codex는 Git 기록도 보관해 약 60 MB). Antigravity는 skill의 처음 24 KB만 로드하며, 전체 지침은 서버의 workflow 도구가 제공합니다. Muse는 아직 지원하지 않습니다. 호스트 표와 검증 범위

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

모든 MCP 클라이언트:

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

Node.js가 없다면 독립 바이너리(CLI)를 설치하고 "command": "figlens", "args": ["mcp"]를 사용하세요. 새 세션을 열고 figlens 도구가 목록에 나타나는지 확인하세요(Claude Code에서는 /mcp). skill을 따로 설치할 필요는 없습니다. mcp 뒤에 --root <dir>를 붙이면 figlens가 읽고 쓸 수 있는 폴더를 제한할 수 있습니다.

MCP 시작 인수

클라이언트의 args에서 mcp 뒤에 지정하세요. MCP 시작 옵션은 이 두 가지뿐이며, 모두 선택 사항이고 반복할 수 있습니다.

옵션	의미
`--root DIR`	`DIR` 및 하위 폴더에서 디자인 읽기와 내보내기를 허용합니다. 생략하면 figlens의 추가 경로 제한 없이 OS 권한이 적용됩니다. 현재 프로젝트로 제한되지 않으며 컴퓨터를 자동 검색하지도 않습니다.
`--storage-root DIR`	`DIR` 및 하위 폴더에서 명시적으로 요청한 사용자 지정 인덱스 저장소를 허용합니다. 기본 저장 위치를 선택하거나 변경하지 않습니다.

기존 디렉터리의 절대 경로를 사용하세요. 각 옵션과 경로는 별도 배열 항목입니다. 여러 폴더에는 옵션을 반복하세요. --root는 경로 경계이지 관리자 권한이 아니며, figlens MCP만 제한하고 agent의 다른 도구는 제한하지 않습니다.

디자인/출력 루트 두 개와 허용된 저장소 루트 두 개의 예:

{
  "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"
      ]
    }
  }
}

figlens mcp --storage 옵션은 없습니다. 실제 위치는 index tool의 storage 인수(허용된 저장소 루트 내 절대 경로) 또는 CLI figlens index prepare design.fig --storage /absolute/storage-a로 선택합니다. prepare 후에는 workspace 위치를 기억하므로 재시작이나 호스트 변경 후에도 storage나 --storage-root 없이 재사용합니다. 사용자 지정 위치가 없으면 사용자별 기본 디렉터리를 사용하며 저장소 플래그는 필요 없습니다.

커밋되는 설정에 이 경로를 고정하지 않거나 Git worktree 사이에서 디자인을 공유하려면 커밋되는 설정의 root를 참고하세요.

여러 저장소 루트는 허용 위치만 늘립니다. 각 storage는 여전히 한 위치를 선택하며 인덱스를 분산, 동기화 또는 백업하지 않습니다. 다른 루트를 지정하는 것만으로 기존 workspace 데이터베이스를 옮길 수 없으며, figlens는 충돌하는 위치를 거부합니다.

Pi

패키지 하나에 CLI, MCP, viewer, /figlens 명령과 skill이 모두 들어 있습니다:

pi install npm:@runkids/figlens

Pi 확장 가이드

OpenCode V2

OpenCode V2에서 패키지를 설치하세요:

opencode plugin add @runkids/figlens

호스트를 다시 시작한 뒤 /figlens help를 실행하세요. OpenCode V2

OMP

OMP에서 같은 패키지를 설치하세요:

omp plugin install @runkids/figlens

호스트를 다시 시작한 뒤 /figlens help를 실행하세요. OMP

CLI

npm으로 실행하거나 독립 바이너리를 설치하세요:

npx @runkids/figlens --help                                                                # Node.js 18+, 설치 불필요
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는 해석한 패키지 버전의 바이너리를 실행합니다. 스크립트로 설치했다면 figlens update, Homebrew로 설치했다면 brew upgrade figlens로 업데이트하세요. 바이너리는 macOS(Apple silicon, Intel), Linux(arm64, x86_64), Windows(x86_64)를 지원합니다.

CLI를 사용하는 에이전트는 figlens workflow build(그 밖에 audit, images, search, plan, planning-details, 명시적으로 요청할 때만 쓰는 yolo)로 가이드를 읽습니다. 내용은 항상 바이너리 버전과 일치합니다. skill에서 읽을 수도 있습니다.

CLI 레퍼런스

에이전트 skill (선택 사항)

skill은 내장 가이드와 같은 흐름을 에이전트에게 알려 줍니다: frame을 찾고, bundle을 조금씩 읽고, 범위를 정해 계획하고, 실행 중인 UI를 디자인과 비교합니다. 지침만 담고 있으므로 CLI나 MCP와 함께 사용하세요. MCP와 Pi 설정에서는 필요하지 않습니다.

추천: skillshare. skill을 한 번 설치하면 사용하는 모든 에이전트에 동기화할 수 있습니다:

skillshare install github.com/runkids/figlens/skills/figlens
skillshare sync

같은 도구로 해당 에이전트들의 figlens MCP 연결도 설정할 수 있습니다:

skillshare mcp add figlens --global --target claude --target codex --target cursor --no-tui -- npx -y @runkids/figlens mcp
skillshare sync mcp --global

skill을 설치하는 다른 방법:

npx skills add runkids/figlens --skill figlens   # Skills CLI

또는 이 저장소나 release 아카이브의 skills/figlens/를 에이전트의 skills 디렉터리(Claude Code: ~/.claude/skills/)에 복사하세요. 설치한 skill은 바이너리와 별도로 업데이트됩니다. figlens workflow는 항상 바이너리와 일치합니다.

그런 다음 화면을 요청하세요.

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.

에이전트는 frame을 찾고 디자인 데이터, 에셋, 참조 이미지를 bundle로 묶은 뒤 프로젝트의 기술 스택으로 화면을 구현합니다. 공통 워크플로가 폰트와 에셋 확인을 안내하며, 부족한 항목은 보고하면서 기록된 대안으로 레이아웃 구현을 계속합니다. 변경된 파일과 브라우저 비교 결과를 보여 달라고 요청하세요.