pi-figma

A pi extension that lets the agent read Figma files without drowning in tokens.

---

What the extension does

Raw Figma REST responses are enormous — a single design file can return 10–100 MB of JSON, most of which is metadata the LLM will never use (vector paths, gradient stops, blend modes, render bounds). Dropping that directly into an agent's context is wasteful and often blows past the context window entirely.

pi-figma sits between pi and the Figma REST API and does three things:

1. Transforms every response into a compact shape before returning it. Hex colors instead of 0–1 RGB, integer bboxes, auto-layout essentials only, vectors stripped. On a real frame we measured 84.9% size reduction vs the raw Figma response.
2. Caches by Figma's native version field. When the file hasn't been edited, repeat calls in the same session are local disk reads (~1 ms). When a designer edits, the version string changes and we refetch automatically.
3. Ships a skill (skills/figma/) that teaches the model cost-ordered tool selection — always use figma_copy before figma_inspect, always figma_map before fetching subtrees, never dump the whole file.

The extension exposes four tools the agent can call directly and one utility command (/figma-cache-stats).

What this is not

• Not a Figma plugin (those run inside Figma itself).
• Not the Figma Dev Mode MCP server (that's a separate paid product that requires Figma Desktop open).
• Not a web scraper. Figma's canvas is WebGL, so CDP-based approaches don't see node data.

---

Install

From npm (recommended)

# global — available in every pi session
pi install npm:@originintelligence/pi-figma

# or project-local — only for this project
cd your-project
pi install -l npm:@originintelligence/pi-figma

From git

pi install git:github.com/sanchezcodes/pi-figma

Pin a version with @vX.Y.Z. Git installs skip pi update when pinned.

From a local checkout (for development)

If you've cloned the repo and want pi to load your working copy directly — useful for iterating on the extension itself:

pi install /absolute/path/to/pi-figma
# or project-local:
pi install -l /absolute/path/to/pi-figma

Pi reads local paths directly — no copying, no rebuild step. Any code change in pi-figma/ is picked up the next time pi starts (or when you run /reload in an active session).

Verify it loaded:

pi
> /extension-status      # should list pi-figma

---

Set up

The extension needs a Figma personal access token. Generate one at https://www.figma.com/developers/api#access-tokens — only the File content read scope is required for v1.

Option A — env var (recommended)

Add to ~/.zshrc (or ~/.bashrc):

export FIGMA_PAT=figd_XXXXXXXXXXXXXXXXXXXX

Reload with source ~/.zshrc or open a new terminal. Launch pi normally.

Option B — config file (fallback)

mkdir -p ~/.pi-figma
echo '{"pat":"figd_XXXXXXXXXXXXXXXXXXXX"}' > ~/.pi-figma/config.json
chmod 600 ~/.pi-figma/config.json

The extension checks FIGMA_PAT first, then falls back to this file. Useful if you can't modify shell rc files (shared hosts, locked-down macs).

How to know it's working

In a pi session:

> map this Figma file https://www.figma.com/design/SOME_KEY/Name

Pi should call figma_map and return a list of pages/frames. If it errors with "No Figma token found", the env var isn't visible to the pi process — usually because you exported in .zshrc but didn't restart the terminal.

---

Capabilities

Four tools, ordered cheapest to most expensive. The skill in skills/figma/ tells the model to prefer the cheaper one whenever possible.

Tool	What it returns	Typical payload
figma_copy	Flat list of UX text: { id, path, text } per TEXT node	smallest
figma_tokens	Registered design-system Styles (names only, no resolved values)	small
figma_map	Page/frame tree: { id, name, type } at configurable depth	small
figma_inspect	Compact layout + visuals for one or more nodes (Dev-Mode-style)	medium

Accepted inputs

• File: a raw key (abc123XYZ) OR any Figma URL (figma.com/file/..., figma.com/design/...).
• Node IDs: 1:234 (API form), 1-234 (URL form), or a full URL with ?node-id= — all parsed automatically.

What every tool returns

• Hex colors (#1a80e6) or rgba() when alpha < 1 — never Figma's raw 0–1 RGB objects.
• Integer bboxes as [x, y, w, h]. No sub-pixel noise.
• Auto-layout essentials only: direction, padding, gap, radius. Skipped when at defaults.
• truncatedChildren: N counter when depth is capped — the agent knows what it didn't see.
• No vector path data, gradient stops, effect details, render bounds, export settings, blend modes (unless non-default).

Utility command

/figma-cache-stats

Shows current disk usage of ~/.pi-figma/cache/.

Typical workflows the skill teaches

• "Convert this frame to code" → figma_map → find frame id → figma_inspect(file, [id], depth=5).
• "Audit copy for typos" → figma_copy(file).
• "What design tokens exist?" → figma_tokens(file).
• "Does this component match the DS?" → figma_tokens for DS context → figma_inspect on the instance → compare.

---

Architecture (brief)

pi-figma/
├── src/
│   ├── index.ts        # extension entry: registers tools + /figma-cache-stats
│   ├── client.ts       # REST fetch, auth resolution, URL/node-id parsing
│   ├── cache.ts        # gzipped disk cache, version-keyed, bounded at 2 versions/file
│   ├── transforms.ts   # raw Figma → compact (the token-saving layer)
│   ├── types.ts        # narrow types for what we actually consume
│   └── tools/
│       ├── map.ts
│       ├── inspect.ts
│       ├── copy.ts
│       └── tokens.ts
├── skills/figma/SKILL.md
└── scripts/smoke.ts    # end-to-end test script

Rule of the house: no code path returns a raw Figma response to the LLM. The content text in every tool is always the output of a transforms.ts function.

---

Known limitations

• figma_tokens misses Figma Variables. v1 only reads the top-level styles map on /v1/files/:key. Modern files increasingly use Variables instead (separate endpoint at /v1/files/:key/variables/local). If figma_tokens returns zeroes on a file you know has colors, fall back to figma_inspect on a consuming node and read its fill. Fixing this is the #1 item on the v0.2 roadmap.
• Personal access tokens are broad. A Figma PAT has access to every file your account can see. Generate a separate PAT with minimal scope if this worries you.
• Large sections still produce large output. figma_inspect on a SECTION containing 12 full screens returns ~60 KB even after transform. The skill tells the agent to drill into a single frame when an inspect result is oversized, but it can still happen. If you see this, instruct the agent: "inspect just the first child, not the whole section."

---

Roadmap

v0.2 — ordered by proven need:

1. Variables support in figma_tokens — the big one, see limitation above.
2. figma_export(file, nodeIds, format, scale) — render frames to PNG/SVG/PDF. Named after Figma's "Export" button.
3. figma_find(file, query) — locate nodes by name pattern.
4. figma_components(file) — component/variant registry.
5. detail: "full" param on figma_inspect — opt-in unredacted fields (effects, gradient stops) for DS reverse-engineering.

v0.3+ — stretch:

• Webhook ingestion for "notify on file change".
• Companion Figma plugin for inside-Figma selection → tool-call bridging.
• OAuth flow alternative to PAT, for shareable team setups.

---

Testing

Typecheck:

cd /path/to/pi-figma
npm install
npm run typecheck

End-to-end smoke test against a live file (requires FIGMA_PAT in env):

npx -y tsx scripts/smoke.ts

The smoke script exercises all four tools against a real Figma file and reports payload sizes, fetch times, and cache-hit latencies. Use it as a regression harness after any change to client.ts or transforms.ts.

---

License

MIT — see LICENSE.