figmosha2: Instructions file for Codex

Figmosha 2.0 — agent instructions

For any coding agent working in this repo: Codex reads this file directly, Claude Code through CLAUDE.md (which just imports it). Machine-specific paths and hosts live in CLAUDE.local.md (gitignored) — read it first if it exists, whichever agent you are.

Drive Figma by sending JS code through a local bridge that's connected to a custom plugin running inside Figma Desktop.

How to send code

macOS / Linux: there is no python command on a stock Mac — wherever this file says python figmosha.py, run ./venv/bin/python figmosha.py (or python3 figmosha.py).

# Preferred — subcommand-style
python figmosha.py exec "return figma.currentPage.name"
python figmosha.py exec --file script.js

# Shorthand (auto-prepends `exec`)
python figmosha.py "return figma.currentPage.name"

# High-level commands (covered below) save tokens for common operations
python figmosha.py text 185:21880 "Привіт"
python figmosha.py variant 185:21883 "Property 1=Default"

# Quick HTTP (no Python needed)
curl -s -X POST http://localhost:8787/exec \
  -H 'Content-Type: application/json' \
  -d '{"code":"return figma.currentPage.id"}'

# Status
curl -s http://localhost:8787/status   # {"plugin_connected": ..., "files": [...], "pending": 0, "abandoned": []}

Multiple files: targets (-T) — READ THIS FIRST

The bridge holds one connection per open Figma file that is running the plugin, not one globally.

python figmosha.py targets                      # name / doc id / fileKey / conn / queue (busy, waiting)
curl -s http://localhost:8787/targets

# -T is a per-subcommand flag — it goes AFTER the subcommand, never before it
python figmosha.py exec "return figma.root.name" -T "Component Library"
python figmosha.py tree 123:456 -T "Component Library"
curl -s -X POST http://localhost:8787/exec -d '{"code":"...","target":"Icons"}'

target matching (resolve_target in bridge.py): document id (the doc column, 6+ chars) → connection id → exact file name (case-insensitive) → exact fileKey → unambiguous substring of the name.