Skip to main content

​
How Glue Works

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

Compile Time

JSX instrumentation injects metadata attributes into every host element at build time.

Runtime

You select and annotate elements in the Glue desktop app while your dev server runs.

Agent Handoff

Annotations are exported as JSON + Markdown specs that Claude Code can consume directly.

​
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: 
// 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
Only host elements (lowercase tags) are instrumented. React components like <Button> or <CustomForm> are not — because only host elements render to the DOM.

​
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:
PrioritySelector TypeStability
105data-agent-idHighest
100id attributeHigh
95data-testidHigh
85Unique CSS classesMedium
70Path selectorLow
50nth-childLowest
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