# Finish Line

**From the final frame to the first line of code.**

![Finish Line cover](assets/finish-line-cover-v1.png)

[![CI](https://github.com/vypravec/finish-line/actions/workflows/ci.yml/badge.svg)](https://github.com/vypravec/finish-line/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/vypravec/finish-line)](https://github.com/vypravec/finish-line/releases/latest)
[![License: MIT](https://img.shields.io/badge/license-MIT-7C5CFC.svg)](LICENSE)

Finish Line is a free, open-source Figma handoff inspector with an optional local MCP bridge for Codex, Claude Code, Cursor, and other compatible agents. It runs as a development plugin in Figma Design, without requiring Dev Mode or a Finish Line account.

There is no Finish Line backend, analytics, subscription, paid upgrade, or feature gate.

> Finish Line is an independent open-source project. It is not affiliated with, endorsed by, or distributed through Figma.

## What it does

- Inspects frames, components, instances, layout, constraints, fills, strokes, effects, typography, variables, styles, and nested layers.
- Recreates the familiar box-model view for border, padding, and content measurements.
- Copies developer-ready values with token-aware copy behavior.
- Generates starter code for CSS, Tailwind CSS, React + CSS Modules, SwiftUI, Jetpack Compose, and Flutter.
- Exports SVG and PNG assets individually or in bulk.
- Connects the open Figma file to an agent through a bridge bound to `127.0.0.1:3846`.
- Lets agents inspect selections, navigate the current page, render previews, and generate code.
- Copies a node-specific `finish-line://` link that can be pasted into an agent prompt to target the exact layer, even after the Figma selection changes.
- Supports typed canvas edits that remain blocked until the user explicitly approves them inside Finish Line.

## Quick start

### 1. Download Finish Line

Clone the repository:

```bash
git clone https://github.com/vypravec/finish-line.git
cd finish-line
```

You can also use GitHub's **Code → Download ZIP** option and extract the archive. Release builds are committed, so the Figma inspector does not require a local build.

### 2. Install the Figma plugin

1. Open the Figma desktop app.
2. Open any Figma Design file.
3. Go to **Plugins → Development → Import plugin from manifest…**.
4. Select `manifest.json` from the Finish Line folder.
5. Run **Finish Line** from **Plugins → Development**.

The Inspect tab is now ready. Keep the repository folder on your computer because Figma loads the development plugin from that location.

### 3. Connect an agent (optional)

Agent support requires Node.js 20 or newer. The Agent tab includes the same guided setup and a live connection test.

#### Codex

```bash
codex plugin marketplace add vypravec/finish-line
codex plugin add finish-line@finish-line
```

Start a new Codex task, open **Finish Line → Agent** in Figma, and click **Connect local agent**. Then ask:

```text
Use $finish-line to inspect my current Figma selection.
```

For an unambiguous handoff, select a layer and click the link icon beside its dimensions. Paste the copied `finish-line://node/...` URL into the prompt. Finish Line resolves that exact node in the connected file instead of relying on whatever is selected when the agent responds.

#### Claude Code

```bash
claude plugin marketplace add vypravec/finish-line
claude plugin install finish-line@finish-line
```

Start a new Claude Code session and invoke `/finish-line:finish-line`, or describe the Figma task normally.

#### Cursor and other MCP clients

See the complete [installation guide](INSTALL.md) for the stdio configuration, update instructions, uninstall steps, and troubleshooting.

## How the agent connection works

```text
Codex / Claude Code / Cursor
              ↕ MCP over stdio
        local bridge process
              ↕ WebSocket on 127.0.0.1:3846
       Finish Line in Figma
              ↕ official Figma Plugin API
       currently open Figma file
```

The bridge is local and Finish Line has no remote server. When you use a cloud-hosted agent, however, the MCP client may send selected design context to that agent's provider under its own terms and privacy policy. See [Privacy](PRIVACY.md) for the exact data flow.

The plugin must remain open while an agent is connected. Closing Finish Line ends the connection and clears the bridge's in-memory selection snapshot.

Finish Line node links contain the node ID, page ID, readable node/page names, and a random plugin-session token. They do not contain layer contents, generated code, account credentials, or a Figma file key. A Finish Line link expires when the plugin window is closed or reloaded; copy a new link for the next session.

## MCP tools

| Tool | Purpose |
| --- | --- |
| `finish_line_status` | Check the bridge, plugin, and current selection state |
| `get_selection` | Read the complete handoff snapshot for the current selection |
| `inspect_link` | Resolve a copied Finish Line link or a Figma URL containing `node-id` |
| `inspect_node` | Inspect a specific node by ID |
| `get_page_outline` | Read a bounded layer tree for the current page |
| `get_selection_preview` | Render a PNG preview as an MCP image block |
| `get_generated_code` | Return code, color tokens, and text styles in one of six targets |
| `select_nodes` | Select and reveal layers without changing document content |
| `apply_design_operations` | Submit a typed batch of canvas changes for in-Figma approval |

Canvas operations can create frames, rectangles, ellipses, text, and component instances; update supported properties; duplicate or delete nodes; and set the selection. Every content-changing batch is shown in Finish Line before anything is applied.

## Privacy and safety

- The Agent connection is opt-in and never starts from the Figma plugin automatically.
- `manifest.json` allows only `ws://localhost:3846`.
- The bridge binds exclusively to `127.0.0.1`, not the local network.
- There is no Finish Line account, analytics collector, remote API, or stored AI credential.
- Agent writes use bounded, typed operations rather than `eval` or arbitrary JavaScript.
- Every document-changing agent request requires explicit approval in Figma.
- Preferences are stored through Figma's local plugin storage; bridge state is kept in memory only.

Read the full [privacy policy](PRIVACY.md) and [security policy](SECURITY.md) before using Finish Line with confidential designs.

## Updating

Pull the newest release and rebuild only when you are developing from source:

```bash
git pull --ff-only
npm ci
npm run build
```

Restart Finish Line in Figma. For Codex, refresh the marketplace and reinstall the plugin if an update is not picked up automatically:

```bash
codex plugin marketplace upgrade finish-line
codex plugin add finish-line@finish-line
```

Then start a new task so Codex loads the updated skill and MCP tools.

## Development

Requirements: Node.js 20 or newer and the Figma desktop app.

```bash
npm ci
npm run watch
```

Reload Finish Line in Figma after UI or plugin-controller changes. The complete automated release gate is:

```bash
npm test
```

It validates both TypeScript targets, the inline UI, code generators, preferences, agent approvals, Codex and Claude manifests, the shared skill, production bundles, and a real MCP stdio/WebSocket integration flow.

See [CONTRIBUTING.md](CONTRIBUTING.md) for development conventions and [RELEASE.md](RELEASE.md) for the release checklist.

## Releases

- `v2.1.3` — one clear Agent setup entry point without a duplicate installation card.
- `v2.1.2` — streamlined Agent handoff with a live shared-selection preview and a clearer link action.
- `v2.1.1` — official Finish Line icon across Codex and the Figma plugin, with consistent host-style corner masking.
- `v2.1.0` — exact-node links for unambiguous agent prompts, plus linked-node validation and native skill support.
- `v2.0.0` — local agent bridge, native Codex/Claude packaging, guided setup, previews, navigation, and approval-gated canvas edits.
- `v1.0.0` — permanently archived offline inspector release without the agent bridge.

Release notes are maintained in [CHANGELOG.md](CHANGELOG.md).

## Support

Use [GitHub Issues](https://github.com/vypravec/finish-line/issues) for bugs, setup questions, and feature proposals. See [SUPPORT.md](SUPPORT.md) before filing an issue.

If Finish Line saves you time, optional support is available on [Ko-fi](https://ko-fi.com/B5R525SOQ7). Contributions never unlock additional features.

## License

Finish Line is available under the [MIT License](LICENSE).