figmog: fold-backed local mirror of a Figma file

[hhff]

Hackathon submission

Note: this PR targets our own fork's main, not upstream — the template is filled in to prep the eventual upstream submission, but the acknowledgment box is deliberately left unchecked (that submission is a separate, explicit step).

category

pick one:

• agent support
• performance
• novel interface / gaming

team

• project name: figmog
• team / author name(s): hhff / sanctuary.computer
• contact (optional): hugh@sanctuary.computer

what you built

figmog turns one Figma file into a local, lightning-fast, agent-queryable database — and then becomes the only Figma MCP server an agent needs: a cached proxy in front of Figma's native tooling, backed by a fold mirror.

The mirror (v1). Figma has no delta API and its file endpoints are Tier-1 rate limited. figmog synthesizes the missing delta API from fold's KeyedStream upsert semantics: poll the cheap Tier-3 metadata endpoint, spend one Tier-1 fetch only when last_touched_at moves, flatten the document into deterministic per-node records, and upsert-diff them through one atomic transaction into 14 materialized sinks (node table, children multimap, BM25 text search, inverted indexes for instances/styles/variables/types, design-system tables, proxy cache). A byte-identical re-pull pushes zero deltas (delta-probe tested); one renamed layer costs exactly one retract/insert pair.

The MCP server (v2). figmog serve is an MCP stdio server with the sync loop built in — one process, always fresh. 17 figmog_* tools answer from the mirror at zero API cost, including whole-file structural queries nothing else offers: figmog_search (BM25), figmog_where (match any JSON pointer across every node), figmog_at (spatial hit-test), figmog_stats, figmog_path, figmog_instances, figmog_vars, and more.

The cached proxy (v3). With the Figma desktop app running (Dev/Full seat), figmog discovers the native Dev Mode MCP server's tools at startup and re-exposes them verbatim — get_design_context, get_screenshot, get_variable_defs, all of them, native output formats passed through untouched — with responses cached by (tool, args, file version), so a screenshot of an unchanged frame is fetched once, ever. Agents connect to figmog alone and get both worlds; the initialize instructions steer tool choice. CLI parity via figmog tools / figmog call <tool> --args '<json>'. Pull also opportunistically syncs Enterprise variables/local (silently skipped on other plans; plugin-export import + boundVariables inference remain as fallbacks).

Design docs: docs/superpowers/specs/2026-08-15-figmog-build-design.md (+ plans in docs/superpowers/plans/).

Upstream finding (not patched here): fold's Table<K, V> panics when K's postcard encoding is empty (e.g. K = ()) — lsm-tree forbids empty keys. figmog keys its singleton meta row by u8 instead. Also: fold's store-open panics on lock contention; figmog translates these to clean errors at its own layer.

how to run

# from repo root
export FIGMA_TOKEN=figd_…   # figma.com → settings → security → personal access tokens
cargo run -p figmog -- pull "https://www.figma.com/design/<key>/<name>"
cargo run -p figmog -- search "pricing card"
cargo run -p figmog -- stats

# as an MCP server for Claude Code (with built-in sync + native-tool proxy):
cargo build -p figmog
claude mcp add figmog -- $PWD/target/debug/figmog serve "https://www.figma.com/design/<key>/<name>"

Offline demo without a token: save any GET /v1/files/:key response as JSON, then figmog pull --from-file resp.json --db /tmp/demo and figmog serve --no-upstream --no-watch --db /tmp/demo.

demo / notes

• 112 tests: flatten determinism (byte-identical postcard), delta-probe churn arithmetic (exact push counts), mid-transaction rollback, watch/backoff state machine, MCP protocol contract (15 unit cases), upstream client incl. SSE parsing + session/protocol-version headers against an in-process HTTP fake, cache hit/miss/eviction/collision-guard, proxy routing + isError handling, serve e2e over real stdio incl. lock-contention behavior, variables import/inference/Enterprise-sync round trips.
• cargo test -p figmog, cargo test -p fold, cargo clippy -p figmog --no-deps -- -D warnings, cargo fmt -p figmog --check all green; zero diff to fold/ese/anny.
• Built via spec → plan → subagent-driven TDD with per-task review, two adversarial whole-branch review passes, and empirically-verified fix rounds.

checklist

• i forked bog-kit and built my project in this fork
• my project is runnable from this pr (crate name and run command above)
• i selected exactly one category
• this pr is my official hackathon submission acknowledgment

🤖 Generated with Claude Code

[hhff]

New: figmog bench — the load-test demo.

One command, no setup: cargo run --release -p figmog -- bench generates a deterministic 10k-node synthetic Figma file, times the engine (cold sync ~99ms for 10k records ≈ 100k records/s; byte-identical re-pull: 7ms, zero churn), then spawns the real MCP server over stdio and hammers it with 5,000 mixed queries (search/node/where/stats/tree/instances) — ~130 req/s sustained, per-query p50s in the low milliseconds (Apple M4, dev profile).

Real-file mode: figmog bench <figma-url> (needs FIGMA_TOKEN) runs the same load test against a mirror of your actual file — costing exactly one Tier-1 API call — and then measures Figma's own /nodes endpoint latency side-by-side (5 calls by default, --skip-api to opt out), reporting the speedup factor and the budget math: at Figma's ~10 req/min Tier-1 limit, the same 5,000-query workload would take ≈8.3 hours; figmog served it in ~38 seconds.

--json for machine-readable results. 124 tests green.

🤖 Generated with Claude Code

[hhff]

figmog bench --interactive — the live REPL.

The bench now has a demo mode where you watch every request fire in real time:

$ cargo run --release -p figmog -- bench --interactive
figmog> search hero button
#   1  figmog_search      q="hero button"            1.82ms  4 hits
figmog> node 12:7
#   2  figmog_node        id=12:7                    1.13ms  "Hero Frame"
figmog> run 500
#   3  figmog_search      q="garden panel"           1.76ms  9 hits
#   4  figmog_where       /layoutMode=VERTICAL       2.90ms  120 hits
…waterfall of 500 lines…
figmog> report        # session-wide p50/p95/p99 per tool
figmog> quit

Every local tool has a shorthand (search, node, tree, where, at, stats, instances, …) plus a raw call <tool> <json> escape hatch. In real-file mode (bench <figma-url> --interactive), api node <id> fires an actual Figma API request timed the same way — the live side-by-side (~2ms local vs hundreds of ms + rate limits remote) is the demo's money shot. Latency-colored output (TTY-gated ANSI, zero deps), 145 tests green.

🤖 Generated with Claude Code

[hhff]

Multi-file serve + graduation notice.

figmog serve is now a multi-file server: zero-config startup (figmog serve with no args), every tool takes an optional file (URL or key), files auto-mirror on first reference, figmog_open/figmog_files manage mirrors, round-robin watch keeps them all fresh. 162 tests green.

This project has graduated to its own repo: https://github.com/sanctuarycomputer/figmog — standalone crate, fold via pinned git dependency on flowercomputers/bogkit, binaries on GitHub Releases. This PR remains the hackathon artifact; active development continues there.

🤖 Generated with Claude Code