> ## Documentation Index
> Fetch the complete documentation index at: https://buildwithglue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How Glue Works

> Understand Glue's three-phase system: compile-time instrumentation, runtime annotation, and agent handoff

# How Glue Works

Glue connects your UI to coding agents through a three-phase pipeline: **compile-time instrumentation**, **runtime annotation**, and **agent handoff**.

<Steps>
  <Step title="Compile Time" icon="code">
    JSX instrumentation injects metadata attributes into every host element at build time.
  </Step>

  <Step title="Runtime" icon="pen">
    You select and annotate elements in the Glue desktop app while your dev server runs.
  </Step>

  <Step title="Agent Handoff" icon="robot">
    Annotations are exported as JSON + Markdown specs that Claude Code can consume directly.
  </Step>
</Steps>

## Phase 1: Compile-Time Instrumentation

When you run `glue run npm run dev`, Glue instruments your JSX at compile time. Every **host element** (native HTML tags like `<button>`, `<div>`, `<input>`) gets `data-agent-*` attributes injected automatically:

```jsx theme={null}
// Your source code
<button className="primary">Click me</button>

// What renders in the browser
<button
  className="primary"
  data-agent-id="auto:K8M2ZP1A"
  data-agent-source-file="app/components/Button.tsx"
  data-agent-source-line="42"
  data-agent-source-col="6"
>
  Click me
</button>
```

These attributes provide:

* **`data-agent-id`** — A deterministic, stable identifier derived from the element's source location (file, line, column, tag)
* **`data-agent-source-file`** — Source file path relative to the project root
* **`data-agent-source-line`** — Line number
* **`data-agent-source-col`** — Column number

<Note>
  Only host elements (lowercase tags) are instrumented. React components like `<Button>` or `<CustomForm>` are not — because only host elements render to the DOM.
</Note>

## Phase 2: Runtime Annotation

With your app instrumented and running, use the **Glue desktop app** to visually annotate UI elements:

1. **Browse your app** in the embedded browser
2. **Click any element** to select it
3. **Glue auto-discovers** the nearest instrumented parent and extracts all `data-agent-*` attributes
4. **Add your comment** describing what you want changed

### Selector Priority

When you select an element, Glue generates multiple selectors ranked by stability:

| Priority | Selector Type      | Stability |
| -------- | ------------------ | --------- |
| **105**  | `data-agent-id`    | Highest   |
| 100      | `id` attribute     | High      |
| 95       | `data-testid`      | High      |
| 85       | Unique CSS classes | Medium    |
| 70       | Path selector      | Low       |
| 50       | nth-child          | Lowest    |

The `data-agent-id` selector is always preferred because it's deterministic and source-linked. Traditional selectors serve as fallbacks.

## Phase 3: Agent Handoff

Run `glue handoff` to export annotations in formats coding agents understand:

* **`latest.json`** — Structured JSON with element references, source locations, selectors, and comments
* **`latest.md`** — Human-readable spec with file paths, line numbers, and acceptance criteria

The agent reads the source location, verifies the element by its `data-agent-id`, and implements the requested change.

## Production Safety

Glue has **zero production impact**:

1. **Conditional compilation** — Instrumentation only runs in development mode
2. **Dev-only dependencies** — All Glue packages are `devDependencies`
3. **No runtime code** — Attributes are inert data; no JavaScript executes for Glue in the browser