Pin2Patch

Turn Figma comment pins into agent-ready tasks and tested code patches from the terminal.

Comment

Pin2Patch

Pin2Patch is an agent-native CLI that turns a Figma review thread, pinned node context, and screenshot into a durable coding task, then safely returns implementation and test evidence to the original root comment.

The problem

Design feedback lives inside Figma while coding agents operate in terminals and repositories. Developers repeatedly locate the pin, copy the discussion, capture visual context, restate the request to an agent, verify the patch, and return to Figma to report the result. That handoff is repetitive, lossy, and difficult to audit.

The solution

Figma comment pin
→ pin2patch pull
→ task.md + task.json + node.png
→ Codex implements and runs tests
→ pin2patch reply (dry run)
→ pin2patch reply --send
→ evidence in the original Figma thread

A pulled task contains the root comment and ordered replies, pinned node metadata, a deep link, an optional rendered PNG, versioned JSON for scripts, Markdown for coding agents, and local state that maps reply IDs back to the required root comment ID.

Pin2Patch does not hide another LLM inside the integration. It keeps authentication, retrieval, normalization, caching, and controlled write-back deterministic. Codex performs repository search, implementation reasoning, testing, and the final evidence summary.

Working MVP

The current build includes:

  • pin2patch doctor [figma-url] for runtime, Git, token-presence, and URL checks;
  • pin2patch pull <figma-url> for unresolved review threads;
  • live Figma REST transport plus a credential-free fixture transport;
  • root/reply grouping, unresolved filtering, and orphan-thread preservation;
  • pinned-node metadata and PNG retrieval;
  • Markdown and stable JSON task artifacts;
  • atomic local state and reply-ID-to-root-ID lookup;
  • dry-run replies by default and explicit --send for live writes;
  • a hard refusal to send fixture-backed tasks;
  • a resettable checkout patch target for the demo.

Judge-safe test path

The repository includes realistic API-shaped fixtures, so the central workflow can be evaluated without a Figma account or token:

npm install
npm run check
npm run build

node dist/cli.js pull \
  "https://www.figma.com/design/demoFileKey/Pin2Patch-Demo" \
  --fixture-dir fixtures/figma

node dist/cli.js reply 813730 \
  --message "Implemented and verified. Tests: 4 passed."

The fixture pull creates task.md, task.json, and node.png. The reply command is a dry run and reports that no Figma data changed.

Reproducible Codex demo

The included checkout example starts in a deliberately flawed state. Its generated review task asks for 16px mobile padding, the price below the title, reuse of the secondary button style, preservation of the desktop layout, and passing checks.

Codex reads the task, patches the two small frontend files, and runs four behavior checks. The before state fails the three requested changes; the reference final state passes all four checks.

How Codex and GPT-5.6 are used

Codex with GPT-5.6 was used to convert the initial hypothesis into a scoped PRD and technical specification, implement the strict TypeScript CLI, design API-shaped fixtures, create automated tests, diagnose failures, and prepare the documentation.

In the product workflow, Codex reads task.md, inspects the screenshot and repository, maps feedback to the smallest relevant code surface, implements the change, runs tests, and writes result.md for the safe Figma reply preview.

Verification

The current local quality gate passes:

  • strict TypeScript typecheck;
  • 9 test files and 20 passing tests;
  • production build;
  • npm package dry run;
  • credential-pattern and risky-file scans.

The compiled CLI has successfully generated the full fixture task package, skipped a resolved thread by default, mapped a reply ID to its root thread, and produced a dry-run reply with sent: false.

Safety and reliability

  • Review comments are treated as untrusted external input and never executed.
  • Figma tokens are read only at request time and never persisted.
  • Remote writes require explicit --send.
  • Fixture tasks cannot write remotely.
  • Node or image failures degrade to text-only tasks.
  • State and JSON writes use atomic replacement.
  • --no-image and local asset reuse reduce avoidable image calls.

Architecture

TypeScript CLI
├── Figma URL parser
├── live REST client / fixture client
├── comment-thread normalizer
├── node context and screenshot loader
├── Markdown / JSON task renderer
├── atomic local state and comment index
└── safe reply writer

The MVP is local-first and requires no database, web app, hosted backend, OAuth service, background worker, browser extension, or Figma plugin.

Public repository and reproducibility

The complete public source, tests, fixtures, demo, documentation, assets, and CI workflow are available at https://github.com/caixq1996/Pin2Patch. The central judge path is credential-free and reproducible on Node.js 20+.

The live Figma REST transport is implemented and covered through mocked transport tests. Remote write-back remains opt-in behind --send; this submission does not claim that verification modified a user-owned live Figma file.

Built With

Share this project:

Updates