OMP integration · figlens docs

The @runkids/figlens package includes a native OMP extension, shared skill, MCP descriptor and CLI launcher. It imports OMP's SDK, not Pi's compatibility layer. Current local acceptance uses OMP 18.13.2 and Bun 1.4.3; no model run is included.

omp plugin install @runkids/figlens

For a local candidate, install its unpacked package directory or start OMP with -e /absolute/path/to/package. Reload the extension, then use /figlens help.

Local controls:

/figlens preview ./design.fig starts a viewer without a model.
/figlens open ./design.fig --frame 0:1 saves a selection and shows a reference image.
/figlens frame searches the saved file; /figlens frame 0:1 selects directly.
/figlens status, /figlens review and /figlens close read state, review proposals or close this session's viewer.

The figlens_bindings, figlens_propose_bindings and figlens_preview tools use OMP's native read/write/exec approval tiers. Direct commands are trusted extension code, as in Pi; these tiers are not a per-path filesystem sandbox. Review shows evidence, permits four-field edits and conflict resolution, and requires final confirmation. No model tool approves mappings. Noninteractive review leaves proposals pending.

Searching a design. Ask OMP to find copy or a screen in a .fig: it searches the file directly and stores nothing. For repeated searches, ask it to enable an index for that design and a scope (for example "enable an index for ./design.fig, whole file"): the agent uses the host MCP index prepare with the file and scope (no setup command), polls jobs until the build succeeds, and from then on searches the published index by workspaceId and node set to the chosen scope and opens results with inspect, also after a restart or from another host. OMP approves every MCP tool at its write tier and shows the call's arguments, including the index action, but has no per-action rule: in always-ask modes a reset prompts like a prepare, a tools.approval entry for the figlens index MCP tool can deny or always prompt it, and OMP's default yolo approval mode runs it unprompted. The shared skill tells the agent to reset only on the user's explicit request. Indexes go to the figlens state directory, or to a location an earlier --storage prepare remembered; the packaged descriptor starts figlens mcp without --storage-root, so a new custom storage is refused. To allow one, define your own figlens server in OMP's MCP configuration with the arguments mcp --storage-root /absolute/dir and reload; native configuration has priority over the packaged descriptor.

Finding usages. Ask OMP where a component, variable, style or image is used: the agent calls the MCP usages tool with the exact layer or resource id, on the .fig directly (stateless) or, once an index is enabled, by workspaceId, the result's sourceId and the prepared scope; it never prepares, widens or resets an index for it. For a library component, style or variable, it passes library {kind, namespace, key}, taken from the library field of an outgoing usages result on a layer that uses it, with workspaceId instead: the layers in every visible prepared source whose cached copy uses it, with the definition left unresolved. Results carry exact refs, a snapshotId and coverage; a hidden-layer exclusion or a source that changed is reported, not read as "unused". OMP approves it at the same write tier as every MCP tool.

Searching by meaning. Search by meaning or across languages needs an optional local model profile that you download yourself; figlens never downloads one. Ask OMP to list or check it: the agent calls the MCP models tool with list or status, then configure with the profile and the folder you downloaded (inside the server's --root folders when it has any), and searches with mode semantic or hybrid. Without a profile semantic is mode_unavailable and hybrid answers with text results. configure and remove change only the profile record under the figlens config folder; remove keeps the model files. OMP approves models at its write tier like every MCP tool, so list and status prompt in always-ask modes too.

Following changes. Ask OMP to follow a design's changes, which opts in to that scope's index and history: the agent prepares the scope when no index covers it, then calls index track with the workspace and the scope, which builds a baseline as an index rebuild does, then subscribes with watch subscribe, reads changes with that subscriptionId and acknowledges each page it handled with watch ack; watch unsubscribe stops following, and untrack, only when asked, stops recording for everyone and keeps the history. watch subscribe with sources (visible or up to 10 sourceIds) instead of sourceId saves a search, or with library a library item's uses, over that fixed set; removing a member disables it, so unsubscribe and subscribe again. A tracking entry with refreshRequired means the file changed since its last build and index refresh records the change; an empty page never proves the file unchanged. Asking it to watch that scope runs watch start, which holds a lease while its figlens server runs, so each save is recorded without index refresh; stop or the session's end releases it, and the last release lets the shared background runner exit. OMP approves these at the same write tier too. OMP cannot see the --root folders of its configured figlens MCP server, so nothing checks in the background: each model call lists the subscriptions and consumers this session subscribed to or acknowledged (kept in the session file, not the note) and asks the agent to read changes for them.

Searching by image. Ask OMP to enable visual indexing for the design and scope: the agent calls index with action visual on the prepared scope and polls jobs. It then searches by workspaceId with an authorized local PNG in image, or an exact result reference in imageRef, and optional pixel crop; adding text uses mode hybrid. Hash matching works without a model; optional siglip-base configuration through models adds broader visual similarity. Query images are never stored, and similarity does not prove component identity. The live viewer offers the same image, crop and mode controls.

Comparing revisions. Ask OMP what changed between two saved copies of a design: the agent calls the MCP diff tool with old and file (local paths) and pages with nextCursor. Layers match by exact id and type only; unknown means a side stopped or left that layer unexpanded, not that it was removed. It reads both files and writes nothing. OMP approves it at the same write tier as every MCP tool.

OMP discovers the packaged .mcp.json; native user configuration has priority. MCP runs from the package directory, so design paths sent to MCP must be absolute paths on the agent's machine. FIGLENS_BIN overrides both the extension launcher and descriptor bridge; otherwise both use the adjacent npm launcher and its existing cache/download logic.

MCP shortcut limit: the public extension API cannot verify the effective MCP server version or a remote snapshot. /figlens open without an explicit frame, descriptive preview, plan, yolo and map therefore report the unverified state and do not dispatch. The shared skill and host-managed MCP remain available in ordinary conversation. This is partial integration, not full Pi workflow parity. No second MCP client or user configuration rewrite is used.

Each session owns its viewer. Session switch and shutdown abort owned operations and close those viewers. The viewer is a loopback service on the agent machine; remote terminals need access to that machine. Approved mappings remain in the existing .figlens/component-mappings.md format and can be read by Pi.