figma-start-macos

name: figma-start-macos description: Start a Figma design session on macOS — opens Figma, launches the Vibma plugin, and connects via MCP. Uses osascript/AppleScript. Handles common failure modes. Use when starting work or when the connection drops. allowed-tools: Bash, mcp__vibma__connection argument-hint: "[new|reconnect]"

Start or restore a Figma + Vibma MCP session. Adapt to whichever state things are in.

Arguments

• No args or new — full startup: open Figma, new file, launch plugin, connect
• reconnect — skip Figma/plugin launch, just re-establish the MCP connection

Phase 1: Assess current state

Before doing anything, check what's already running:

# Is Figma running?
pgrep -x Figma >/dev/null 2>&1 && echo "FIGMA_RUNNING" || echo "FIGMA_NOT_RUNNING"

Also try connection(method: "get") — if it succeeds, the full stack is already up. Report the document name and skip everything.

Phase 2: Launch Figma (if needed)

Only if Figma is not running:

open -a "Figma"
sleep 3

If Figma IS running but connection failed, the issue is likely the plugin — skip to Phase 3.

Phase 3: Create new file (if new or no args)

Skip this phase for reconnect.

osascript -e '
tell application "Figma" to activate
delay 1
tell application "System Events"
    tell process "Figma"
        keystroke "n" using command down
    end tell
end tell
'

Wait 5 seconds for the file to load. The new file editor takes time.

Possible issues

• Accessibility not granted: osascript will error with "not allowed assistive access". This is a hard block — tell the user: "System Settings → Privacy & Security → Accessibility → enable your terminal app."
• Figma auth expired / login screen: Cmd+N won't work — Figma is showing a browser login or in-app auth wall. This is a hard block. Tell the user: "Figma is showing a login screen. Please sign in manually, then run /figma-start reconnect." Do NOT attempt to automate login — it involves browser redirects and 2FA.
• Figma shows a modal/dialog: Cmd+N may not work. Tell the user to dismiss it manually, then retry.

Phase 4: Launch Vibma plugin

osascript -e '
tell application "Figma" to activate
delay 0.5
tell application "System Events"
    tell process "Figma"
        keystroke "k" using command down
        delay 0.8
        keystroke "Vibma"
        delay 1.5
        keystroke return
    end tell
end tell
'

Wait 4 seconds for the plugin to initialize and connect to the relay.

Possible issues

• Quick actions didn't find Vibma: The plugin may not be installed. Tell the user: "Install Vibma from the Figma Community or run it locally via the manifest."
• Plugin opened but wrong item selected: If connection fails later, this is a likely cause. Ask the user to open the plugin manually (Plugins → Vibma) and retry with /figma-start reconnect.

Phase 5: Connect MCP

1. Call connection(method: "create") to join the channel.
2. Call connection(method: "get") to verify end-to-end connectivity.

Retry logic for get

If get times out, retry up to 3 times with 3-second waits between attempts. The plugin may still be initializing.

Diagnosing failures

If all retries fail, diagnose based on the error:

Phase 6: Confirm

Once get succeeds, report:

• Document name
• Current page
• Any warnings (version mismatch, etc.)

The session is ready.