transitions-refine 0.3.9 → 0.3.11

package/.agents/skills/refine-live/SKILL.md

@@ -1,11 +1,23 @@
 ---
 name: refine-live
-description: Become the live "Refine" agent for the Timeline Inspector. Use when the user runs `/refine live`, asks to "refine live", "go live", "answer refine jobs", or wants the timeline panel's Refine button (LLM mode), Accept button, or grouped scan to be backed by a real agent. Long-polls the local refine relay, reasons about each CSS transition with the transitions-dev skill, posts suggestions back to the browser panel, for "scan" jobs groups the page's transitions into components with open/close phases by reading the source, and for "apply" jobs writes the accepted timing changes into the user's source code.
+description: In-chat fallback for the Timeline Inspector Refine agent. Use when the user runs `/refine live`, asks to "refine live", "go live", or answer refine jobs — but ONLY when no persistent agent is wired (no `npx transitions-refine live`). Prefer `npx transitions-refine live` for run-and-forget (relay spawns agent per click, no idle credit burn). This skill long-polls the relay, posts suggestions, handles scan/apply jobs.
 ---
 
 # Refine Live
 
-Turn yourself into the LLM behind the Timeline Inspector's **Refine** button. While
+## Two modes
+
+**Persistent (recommended — run and forget)**  
+Run `npx transitions-refine live` from your project. The CLI starts the relay and wires `REFINE_AGENT_CMD` so the relay spawns your agent CLI **per Refine click**. No chat loop; idle = zero credit burn. Works hours later as long as the relay process keeps running. Stop with Ctrl-C (or `npx transitions-refine stop`).
+
+**In-chat loop (fallback — this skill)**  
+Run `/refine live` in Cursor/Claude/Codex when the relay is up but has **no** `REFINE_AGENT_CMD`. **You** become the poller via `GET /jobs/next`. The Agent tab stays available only while you keep polling — **each idle poll cycle consumes chat turns/credits**. Say "stop refine" to exit.
+
+Use the in-chat loop only when you cannot wire a persistent agent CLI.
+
+---
+
+Turn yourself into the LLM behind the Timeline Inspector's **Refine** button (**in-chat fallback mode**). While
 this loop runs, the panel's **LLM** tab is "available": each click sends one
 transition here, you reason about it, and your suggestions appear in the panel.
 
@@ -19,15 +31,28 @@ Browser (Refine, LLM tab) ──POST /jobs──► relay ──GET /jobs/next
                           ◄──GET /jobs/:id── relay ◄──POST /jobs/:id/result── YOU
 ```
 
-## The loop — stay live for the whole session
-
-**Keep polling continuously until the user explicitly stops you.** This is the
-only thing that keeps the panel's LLM tab "available", so do not give up on idle.
-A long stretch of `204` responses is *normal and expected* — it just means no one
-has clicked Refine yet. Re-poll immediately every time; never treat repeated
-`204`s as a reason to stop. The relay reports the agent as "available" for ~120s
-after your last poll, so as long as you keep looping you stay live and the user
-never has to re-run `/refine live`.
+## The loop — stay live, but don't burn credits forever
+
+Keep polling so the panel's LLM tab stays "available", but this loop costs chat
+turns/credits even while idle, so it is **not** truly run-and-forget — it has
+three exits, in priority order:
+
+1. **Relay stop signal (authoritative).** `GET /jobs/next` may return `200` with
+   `{"stop": true}`. The relay sends this when the user clicks **Stop** in the
+   panel, or automatically after ~10 min with no jobs. **Always honor it: stop
+   looping immediately**, tell the user the LLM tab will go unavailable and how to
+   resume (`/refine live`), and end your turn. Never re-poll after a stop signal.
+2. **The user says so** — "stop refine", "exit live", etc.
+3. **Your own idle backoff (safety net).** A long stretch of `204`s is normal —
+   it just means no one has clicked Refine yet — but to avoid spending credits on
+   a forgotten loop, **back off as idle grows** instead of hammering immediately:
+   re-poll right away for the first few empty cycles, then pause ~5s between polls,
+   and after ~10 min of unbroken idle stop on your own (same as the relay's
+   auto-stop) and tell the user how to resume. Any real job resets the backoff.
+
+The relay reports the agent as "available" for ~120s after your last poll, so
+short pauses keep you live. A successful job always resets idle, so an active
+session never backs off.
 
 1. **Claim the next job (long-poll).** This call blocks up to ~25s, then returns.
 
@@ -35,8 +60,12 @@ never has to re-run `/refine live`.
    curl -s http://localhost:7331/jobs/next
    ```
 
-   - HTTP `204` / empty body → no work yet. Immediately call it again.
-   - HTTP `200` with JSON → a job. Shape:
+   - HTTP `204` / empty body → no work yet. Poll again, applying the idle
+     backoff above (immediate at first, then ~5s pauses, then stop after ~10 min).
+   - HTTP `200` with `{"stop": true}` → **the loop must end.** Stop polling, tell
+     the user the LLM tab is now unavailable and that `/refine live` resumes it,
+     and end your turn. Do not treat it as a job.
+   - HTTP `200` with a job JSON → work to do. Shape:
 
      ```json
      {
@@ -64,11 +93,11 @@ never has to re-run `/refine live`.
      posting suggestions. Everything below (refineType, steps 3–4) is for the
      normal Refine flow.
    - `refineType` chooses what kinds of suggestions to make (it mirrors the
-     panel's two tabs):
+     panel's two tabs). The tabs scan **independently**, so answer only the one
+     you were asked for:
      - `"small"` (or missing) → **Small refinements**: nudge the existing
-       declarations toward the motion tokens (step 3a) **and**, when it's possible
-       and sensible, *also* suggest swapping the whole transition for a
-       transitions.dev recipe (step 3b).
+       declarations toward the motion tokens **only** (step 3a). Do **not**
+       propose a recipe swap here — that's the Replace tab's separate job.
      - `"replace"` → **Replace transition**: suggest a whole-transition recipe
        swap **only** (step 3b). Do **not** propose motion-token tweaks — skip
        step 3a entirely.
@@ -81,50 +110,74 @@ never has to re-run `/refine live`.
      -d '{"message":"Matching to transitions.dev motion tokens…"}'
    ```
 
-3. **Reason about the transition.** Read `transitions-dev` and apply its
-   `transitions refine` behaviour. Which steps you run depends on `refineType`:
-   - `refineType === "small"` → do step 3a **and** step 3b.
-   - `refineType === "replace"` → do step 3b **only** (skip 3a — no token tweaks).
+3. **Answer in ONE shot — speed matters.** Each click should feel instant, so
+   resolve the job from the data below plus what's already in this skill. Do **not**
+   spawn subagents or run a broad codebase search, and do **not** open the
+   transitions-dev `SKILL.md` — its tokens and decision rules are inlined here.
+   - `refineType === "small"` → step 3a only, with **zero file reads**.
+   - `refineType === "replace"` → step 3b only; open **at most the one** recipe
+     reference file you choose.
 
    First, infer each declaration's **usage** from `label` + `selector` (modal
-   close, dropdown open, tooltip, badge, resize, color/theme change…). Every
-   decision below keys off that usage — match on **intent, not the nearest
-   number**.
-
-   **3a. Motion-token tweaks (only for `refineType === "small"`).** Using
-   `## Motion tokens`:
-   - Pick the motion token that fits the usage — a modal close wants a fast exit;
-     a color/theme change can be slower; spring/back easings suit playful slides,
-     not opacity.
-   - Only propose a change where the current value actually differs.
-
-   **3b. Replace the whole transition (for `small` when sensible, always
-   considered for `replace`).** Judge whether this transition would be better off
-   re-built as one of the twenty-one transitions.dev recipes:
-   - The `transitions-dev` skill stays in the loop — run its `## Decision rules`
-     against the inferred usage to pick the **single** best-fit recipe, then open
-     that recipe's reference file (e.g. `06-modal.md`, `05-menu-dropdown.md`) to
-     read its real timings, easing, distance, scale, and blur.
-   - Only propose a replacement when it is **possible and sensible**: the current
-     declarations are clearly a hand-rolled version of a catalogued recipe, or are
-     missing the structure the usage calls for (e.g. an opacity-only "modal" that
-     should scale, a width tween that should be the card-resize recipe). If the
-     transition already *is* the right recipe, or no recipe genuinely fits, **do
-     not** force one.
-     - For `refineType === "small"`: skip the replace suggestion and let the 3a
-       token tweaks stand alone.
-     - For `refineType === "replace"`: there are no token tweaks to fall back on,
-       so return an **empty** `suggestions` array with a short `summary` saying the
-       transition already fits / no recipe applies.
-   - Emit at most **one** `kind: "replace"` suggestion per job. For `small` it sits
-     alongside the token tweaks (don't drop those); for `replace` it is the only
-     suggestion.
-   - Make its `patch` apply what the panel *can* apply live — the recipe's
-     recommended duration/easing for the property that already transitions (or
-     `"all"`). Name the recipe and its reference file in `title` + `reason` so the
-     user knows the structural parts (keyframes, extra properties, JS hooks) come
-     from running `transitions apply <recipe>` / pasting that reference file. Never
-     invent timings — quote the ones from the reference file.
+   close, dropdown open, tooltip, badge, resize, color/theme change…). Match on
+   **intent, not the nearest number**.
+
+   **3a. Motion-token tweaks (`refineType === "small"` only — no file reads).**
+   Pick the token that fits the usage and propose a change **only where the current
+   value actually differs**.
+
+   - **Durations:** 40ms Stagger (per-item offset) · 80ms Micro (tooltip delay,
+     shake segment) · 150ms Quick (modal/dropdown close, text swap, tooltip
+     appear) · 250ms Fast (icon swap, dropdown/modal open, tabs slide, page
+     slide) · 350ms Medium (panel/toast close) · 400ms Slow (panel open, skeleton
+     reveal, input clear) · 500ms Very slow (emphasis, badge appear, text reveal,
+     success check).
+   - **Default easing — "Smooth ease out":** `cubic-bezier(0.22, 1, 0.36, 1)`
+     (modal/dropdown/panel open+close, page slide, resize, position change).
+   - **Other on-grid easings — LEAVE UNCHANGED:** `ease-out` (tooltip),
+     `ease-in-out` (icon/text swap, text reveal, skeleton reveal), `linear`
+     (shimmer, pulse, spinner), `cubic-bezier(0.34, 1.36, 0.64, 1)` (badge pop),
+     `cubic-bezier(0.34, 3.85, 0.64, 1)` (avatar return).
+   - **Nudge toward Smooth ease out:** generic `ease`, `ease-in`, or any
+     hand-rolled cubic-bezier()/linear() that isn't a token above.
+
+   **3b. Whole-transition recipe swap (`refineType === "replace"` only — no file
+   reads).** Match the inferred usage to ONE recipe below (this list *is* the
+   decision rules — no SKILL.md or reference-file read needed). Emit ONE
+   `kind: "replace"` suggestion whose `patch` carries the **motion-token**
+   duration/easing for the recipe's phase (open vs close) on the property that
+   already transitions (or `"all"`), with a `reference` field naming the file and
+   the recipe in `title` + `reason`. The patch only drives the live preview —
+   exact keyframes/structure come from the user pasting that reference file, so you
+   never need to open it. If no recipe genuinely fits the usage, return an
+   **empty** `suggestions` array with a short `summary`.
+
+   - Card resize — a container changes width/height on a layout change (`01-card-resize.md`)
+   - Number pop-in — a number/digit updates (`02-number-pop-in.md`)
+   - Notification badge — a small dot/badge appears on a trigger (`03-notification-badge.md`)
+   - Text states swap — text content changes in place (`04-text-states-swap.md`)
+   - Menu dropdown — an anchored surface grows from its trigger (`05-menu-dropdown.md`)
+   - Modal open/close — a centered dialog scales up, softer scale-down on close (`06-modal.md`)
+   - Panel reveal — a surface slides into a region with a cross-blur (`07-panel-reveal.md`)
+   - Page side-by-side — slide between list↔detail or step 1↔step 2 (`08-page-side-by-side.md`)
+   - Icon swap — two icons cross-fade in the same slot (`09-icon-swap.md`)
+   - Success check — a checkmark celebration: fade + rotate + bob + stroke-draw (`10-success-check.md`)
+   - Avatar group hover — hover lifts an item in a horizontal stack (`11-avatar-group-hover.md`)
+   - Error state shake — invalid-input shake (`12-error-state-shake.md`)
+   - Input clear with dissolve — clearing a text field (`13-input-clear-dissolve.md`)
+   - Skeleton loader and reveal — placeholder pulses then swaps to real content (`14-skeleton-reveal.md`)
+   - Shimmer text — in-progress / "thinking" text shimmer (`15-shimmer-text.md`)
+   - Tabs sliding — a moving highlight across segmented options (`16-tabs-sliding.md`)
+   - Tooltip open/close — delayed fade+scale in, instant out (`17-tooltip.md`)
+   - Texts reveal — staggered blurred rise of stacked text lines (`18-texts-reveal.md`)
+   - Card hover tilt — 3D tilt toward the pointer (`19-card-tilt.md`)
+   - Plus to menu morph — a circular trigger becomes the surface it opens (`20-plus-menu-morph.md`)
+   - Accordion expand — a collapsible body grows/shrinks in height (`21-accordion.md`)
+
+   Tie-break: prefer the lower-overhead recipe (card resize over panel reveal,
+   dropdown over modal). Only propose a swap when the current declarations are
+   clearly a hand-rolled version of a recipe or are missing the structure the usage
+   calls for; if the transition already *is* the right recipe, return empty.
 
 4. **Post the result** (this completes the job and renders cards in the panel):
 
@@ -148,9 +201,8 @@ never has to re-run `/refine live`.
      }'
    ```
 
-   The example above is a `small` job (token tweaks). When a recipe genuinely
-   fits, include a `kind: "replace"` card — alongside the token tweaks for
-   `small`, or as the **only** suggestion for `replace`:
+   The example above is a `small` job (token tweaks only). A `replace` job instead
+   returns a single `kind: "replace"` card as its **only** suggestion:
 
    ```json
    {
@@ -174,9 +226,10 @@ never has to re-run `/refine live`.
      -H 'Content-Type: application/json' -d '{"message":"…"}'
    ```
 
-5. **Go back to step 1.** Keep looping indefinitely. **Only stop when the user
-   explicitly tells you to** (e.g. "stop refine", "exit live"). Do not stop just
-   because it's been quiet — idle is the normal state between clicks. If you do
+5. **Go back to step 1.** Keep looping, but honor the three exits from
+   [the loop section](#the-loop--stay-live-but-dont-burn-credits-forever): a
+   `{"stop": true}` from the relay, the user telling you to stop, or your own idle
+   backoff/auto-stop after ~10 min quiet. A real job resets idle. Whenever you do
    stop, tell them the LLM tab will go unavailable and how to restart
    (`/refine live`).
 

package/README.md

@@ -29,27 +29,30 @@ npx transitions-refine stop
 
 1. injects one `<script type="module" src=".../inject.js">` into your page (it looks for `index.html`, `public/index.html`, … or pass `--page <path>`),
 2. drops the `refine-live` + `transitions-dev` skills into `.agents/skills/` (so the agent makes token-aware picks),
-3. starts the local relay (which serves the panel at `/inject.js`).
+3. **auto-wires an LLM backend** — it detects the agent hosting this run and points the relay at *its* CLI, so Refine uses the subscription you already have (Cursor → `cursor-agent`, Claude Code → `claude`, Codex → `codex`),
+4. starts the local relay (which serves the panel at `/inject.js`).
 
 Open your app — the panel is now on the page. Press Ctrl-C to stop the relay and remove the injected tag.
 
 ## LLM quality (recommended)
 
-The default answerer snaps each value to the nearest motion token. For *usage-aware* picks (a 300 ms modal close → `Quick` 150 ms, a dropdown open → `Fast` 250 ms), back the panel with an LLM. Two ways:
+The default answerer snaps each value to the nearest motion token. For *usage-aware* picks (a 300 ms modal close → `Quick` 150 ms, a dropdown open → `Fast` 250 ms), back the panel with an LLM.
+
+Plain `npx transitions-refine live` already does this when an agent CLI is available: it prefers the **host agent** so it bills your existing plan, persistently (no `/refine live` loop to keep alive). The CLI must be authenticated once — Cursor: run `cursor-agent` to log in (or set `CURSOR_API_KEY`); Claude Code: run `claude` to sign in; Codex: run `codex` to sign in (or set `CODEX_API_KEY`).
 
 ```bash
-# A) persistent: install/wire the Cursor CLI so the relay answers LLM jobs itself,
-#    per click, with no /refine live loop to keep alive (one-time CLI install)
-npx transitions-refine live --llm
-```
+# auto: use whichever agent hosts this run (cursor-agent / claude / codex)
+npx transitions-refine live
 
-After `--llm`, make sure the CLI is authenticated once: run `cursor-agent` to log in, or set `CURSOR_API_KEY`.
+# force a specific agent regardless of host
+npx transitions-refine live --agent claude   # cursor | claude | codex
 
-```
-# B) in-IDE agent: run this in your editor to become the answerer yourself
-/refine live
+# no agent on the machine? install the Cursor CLI as a fallback
+npx transitions-refine live --llm
 ```
 
+Resolution order: `REFINE_AGENT_CMD` (explicit) → `--agent <name>` → detected host agent → any installed agent → (with `--llm`) install cursor-agent. If none is available the panel falls back to the in-IDE loop — run `/refine live` in your editor to answer jobs yourself (works in Cursor, Claude Code, or Codex; stays live only while that session keeps polling).
+
 You can also point the relay at any one-shot agent CLI via `REFINE_AGENT_CMD` (the relay feeds it the prompt on stdin and reads a JSON result from stdout):
 
 ```bash
@@ -102,6 +105,30 @@ Endpoints: `POST /jobs` (refine, `kind: "apply"`, or `kind: "scan"`), `GET /jobs
 
 Refine suggestions stay as live overrides until you press **Accept**, which is the explicit step that writes them into your source.
 
-## License
-
-MIT
+## Terms & License
+
+> Full terms: https://transitions.dev/terms.html
+
+- **Beta software.** Refine is an early Beta. Features, commands, the panel, and
+  its behavior may change, regress, or be removed at any time without notice. No
+  guarantee of availability, stability, or fitness for any purpose.
+- **Your agent credits.** Refine triggers *your own* AI coding agent (Cursor,
+  Claude Code, Codex, …). Every Refine click and any `npx transitions-refine
+  live` / `/refine live` session consumes *your* provider's tokens/credits —
+  including while a live session sits idle and keeps polling. You are solely
+  responsible for that spend; this project is not liable for and will not
+  reimburse any credits, fees, or overages. Run `npx transitions-refine stop`
+  (or say `stop refine`) when you're done.
+- **The agent changes your code.** Accepting a suggestion writes changes into
+  your source files. Suggestions are AI-generated and may be wrong. Use version
+  control, review every change before committing, and keep backups. Use at your
+  own risk.
+- **No warranty.** The software is provided **"AS IS"**, without warranty of any
+  kind. To the maximum extent permitted by law, the authors are not liable for
+  any damages — direct, indirect, incidental, or consequential, including lost
+  work or lost credits — arising from its use.
+
+### MIT License
+
+MIT — Copyright (c) 2026 Jakub Antalik / Transitions.dev. See
+https://transitions.dev/terms.html for the full license text.

package/bin/cli.mjs

@@ -1,18 +1,21 @@
 #!/usr/bin/env node
 // Refine — transitions.dev live tool.
 //
-//   npx transitions-refine live         # inject the panel + start the relay
-//   npx transitions-refine live --llm   # + install/wire cursor-agent (persistent LLM)
-//   npx transitions-refine stop          # remove the injected <script> tag
+//   npx transitions-refine live              # inject panel + relay; auto-wire your agent CLI
+//   npx transitions-refine live --agent claude   # force an agent: cursor | claude | codex
+//   npx transitions-refine live --llm        # install the Cursor CLI if no agent is found
+//   npx transitions-refine stop              # remove the injected <script> tag
 //
 // `live` sets up the timeline + Refine with no npm install and no source edits
 // of your own:
 //   1. injects one <script type="module" src=".../inject.js"> into your page
 //   2. drops the `refine-live` + `transitions-dev` skills (for token-aware picks)
-//   3. ensures an LLM backend:
-//        --llm  → installs/wires the Cursor CLI (cursor-agent) so the relay
-//                 answers LLM jobs itself, persistently (no /refine live loop).
-//        else   → falls back to /refine live (in-IDE agent) + deterministic.
+//   3. wires an LLM backend so the relay answers jobs itself, persistently (no
+//      /refine live loop). It prefers the agent HOSTING this run — Cursor →
+//      cursor-agent, Claude Code → claude, Codex → codex — so Refine uses the
+//      subscription you already have. Override with --agent <name> or by
+//      exporting REFINE_AGENT_CMD. With no agent available it falls back to the
+//      /refine live in-IDE loop (and --llm can install the Cursor CLI).
 //   4. starts the local refine relay (serves the panel at /inject.js).
 
 import { spawn, spawnSync } from "node:child_process";
@@ -48,6 +51,7 @@ function parseArgs(argv) {
     const a = argv[i];
     if (a === "--page" || a === "-p") args.page = argv[++i];
     else if (a === "--port") args.port = argv[++i];
+    else if (a === "--agent") args.agent = argv[++i];
     else if (a.startsWith("--")) args[a.slice(2)] = true;
     else args._.push(a);
   }
@@ -111,17 +115,68 @@ function dropSkill(name) {
   return existed ? "updated" : true;
 }
 
-// ── agent CLI (for the persistent LLM path) ──────────────────────────────────
-// The relay spawns `REFINE_AGENT_CMD` per job. We point it at cursor-agent so
-// LLM Refine works without a live `/refine live` loop. The binary may not be on
-// the non-interactive PATH, so we probe known install locations and use an
-// absolute path when wiring it up.
-const AGENT_BIN_CANDIDATES = [
-  "cursor-agent",
-  join(HOME, ".local/bin/cursor-agent"),
-  join(HOME, ".cursor/bin/cursor-agent"),
+// ── agent CLIs (for the persistent LLM path) ─────────────────────────────────
+// The relay answers LLM jobs by spawning REFINE_AGENT_CMD per job (stdin =
+// prompt, stdout = JSON). To bill against the account the user ALREADY pays for,
+// we detect which agent is hosting this run and wire ITS CLI: a Claude Code user
+// gets `claude`, a Codex user gets `codex`, a Cursor user gets `cursor-agent`.
+// Detection is by each host's env markers; override with --agent <name> or by
+// exporting REFINE_AGENT_CMD yourself.
+const envHasPrefix = (p) => Object.keys(process.env).some((k) => k.startsWith(p));
+
+const AGENTS = [
+  {
+    key: "cursor",
+    label: "Cursor",
+    // Cursor's agent terminal exports CURSOR_AGENT.
+    host: () => Boolean(process.env.CURSOR_AGENT),
+    bins: [
+      "cursor-agent",
+      join(HOME, ".local/bin/cursor-agent"),
+      join(HOME, ".cursor/bin/cursor-agent"),
+    ],
+    // -p = headless/stdin, --force = auto-allow tool calls. The relay also
+    // auto-appends -p/--trust/--force for cursor-agent; we wire them up front so
+    // the printed command is the real one.
+    cmd: (bin) => `${bin} -p --force`,
+    canInstall: true,
+    auth: "run `cursor-agent` once to log in, or set CURSOR_API_KEY",
+  },
+  {
+    key: "claude",
+    label: "Claude Code",
+    // Claude Code exports CLAUDECODE=1 (+ CLAUDE_CODE_*) in its tools/terminals.
+    host: () => Boolean(process.env.CLAUDECODE || process.env.CLAUDE_CODE_ENTRYPOINT),
+    bins: [
+      "claude",
+      join(HOME, ".claude/local/claude"),
+      join(HOME, ".local/bin/claude"),
+    ],
+    // -p = headless print (prompt on stdin); skip-permissions so apply jobs can
+    // edit files without an interactive approval prompt.
+    cmd: (bin) => `${bin} -p --dangerously-skip-permissions`,
+    canInstall: false,
+    auth: "run `claude` once to sign in",
+  },
+  {
+    key: "codex",
+    label: "Codex",
+    // Codex exec exports CODEX_SANDBOX (+ CODEX_* friends) in its sandbox.
+    host: () => Boolean(process.env.CODEX_SANDBOX) || envHasPrefix("CODEX_"),
+    bins: ["codex", join(HOME, ".local/bin/codex")],
+    // `codex exec -` reads the prompt on stdin; workspace-write so apply jobs can
+    // edit files; skip-git-repo-check so a non-git project root doesn't error out.
+    cmd: (bin) => `${bin} exec --sandbox workspace-write --skip-git-repo-check -`,
+    canInstall: false,
+    auth: "run `codex` once to sign in, or set CODEX_API_KEY",
+  },
 ];
 
+// Host-detection precedence. Claude/Codex export very specific markers; check
+// them BEFORE Cursor so a Claude Code or Codex session launched from inside a
+// Cursor terminal (which still carries CURSOR_*) is not mis-wired to cursor-agent.
+const HOST_PRECEDENCE = ["claude", "codex", "cursor"];
+
 function isRunnable(bin) {
   try {
     return spawnSync(bin, ["--version"], { stdio: "ignore" }).status === 0;
@@ -130,11 +185,20 @@ function isRunnable(bin) {
   }
 }
 
-function findAgentBin() {
-  return AGENT_BIN_CANDIDATES.find(isRunnable) || null;
+function findBin(agent) {
+  return agent.bins.find(isRunnable) || null;
+}
+
+function detectHostAgent() {
+  for (const key of HOST_PRECEDENCE) {
+    const a = AGENTS.find((x) => x.key === key);
+    if (a && a.host()) return a;
+  }
+  return null;
 }
 
-function installAgentCli() {
+// Install the Cursor CLI (the only agent we can fetch non-interactively).
+function installCursorCli() {
   log("• installing the Cursor CLI (cursor-agent) — one-time…");
   const r =
     process.platform === "win32"
@@ -147,15 +211,53 @@ function installAgentCli() {
           stdio: "inherit",
         });
   if (r.status !== 0) log("! the installer exited non-zero — see its output above.");
-  return findAgentBin();
+  return findBin(AGENTS[0]);
 }
 
-// Returns an absolute-ish command string to put in REFINE_AGENT_CMD, or null.
-function ensureAgentCli({ autoInstall }) {
-  const bin = findAgentBin();
-  if (bin) return bin;
-  if (!autoInstall) return null;
-  return installAgentCli();
+// Decide which agent CLI the relay should spawn. Returns either
+//   { cmd, agent, source }          → wire this command (persistent LLM), or
+//   { cmd:null, agent?, reason }    → couldn't wire; caller prints guidance.
+// Precedence: explicit REFINE_AGENT_CMD → --agent <key> → host agent (same
+// subscription) → any installed agent → (with --llm) install cursor-agent.
+function resolveAgent({ wantLlm, forceKey }) {
+  if (process.env.REFINE_AGENT_CMD) {
+    return { cmd: process.env.REFINE_AGENT_CMD, source: "env" };
+  }
+
+  let target = null;
+  if (forceKey) {
+    target = AGENTS.find((a) => a.key === forceKey) || null;
+    if (!target) {
+      return { cmd: null, reason: `unknown --agent "${forceKey}" (use cursor | claude | codex)` };
+    }
+  }
+  if (!target) target = detectHostAgent();
+
+  if (target) {
+    let bin = findBin(target);
+    if (!bin && target.canInstall && wantLlm) bin = installCursorCli();
+    if (bin) return { cmd: target.cmd(bin), agent: target, source: forceKey ? "forced" : "host" };
+    return {
+      cmd: null,
+      agent: target,
+      reason:
+        `detected ${target.label} but its CLI isn't on PATH` +
+        (target.canInstall ? " — re-run with --llm to install it" : ` — install the ${target.label} CLI first`),
+    };
+  }
+
+  // No host detected (plain terminal): use any installed agent, in list order.
+  for (const a of AGENTS) {
+    const bin = findBin(a);
+    if (bin) return { cmd: a.cmd(bin), agent: a, source: "scan" };
+  }
+
+  // Nothing installed: only cursor-agent can be fetched non-interactively.
+  if (wantLlm) {
+    const bin = installCursorCli();
+    if (bin) return { cmd: AGENTS[0].cmd(bin), agent: AGENTS[0], source: "install" };
+  }
+  return { cmd: null, reason: "no agent CLI found" };
 }
 
 function log(msg) {
@@ -186,26 +288,28 @@ function cmdLive(args) {
     else if (r === "exists") log(`✓ ${name} skill already present (v${PKG_VERSION})`);
   }
 
-  // 2.5) ensure an agent CLI so the relay can answer LLM jobs itself — this is
-  //      the persistent path (no `/refine live` loop to keep alive). Installing
-  //      fetches a system binary, so it only happens with explicit opt-in via
-  //      `--llm`. If REFINE_AGENT_CMD is already set we respect it as-is.
+  // 2.5) wire an agent CLI so the relay can answer LLM jobs itself — the
+  //      persistent path (no `/refine live` loop to keep alive). We prefer the
+  //      agent hosting this run so Refine bills the subscription the user already
+  //      has. REFINE_AGENT_CMD (if set) always wins; --agent forces a choice.
   const wantLlm = Boolean(args.llm);
+  const forceKey = typeof args.agent === "string" ? args.agent : null;
   const env = { ...process.env, REFINE_RELAY_PORT: port };
-  let agentBin = null;
-  if (process.env.REFINE_AGENT_CMD) {
-    log(`✓ using REFINE_AGENT_CMD from environment: ${process.env.REFINE_AGENT_CMD}`);
-  } else {
-    agentBin = ensureAgentCli({ autoInstall: wantLlm });
-    if (agentBin) {
-      // Absolute path: the relay spawns via `sh -c`, whose PATH may not include
-      // the CLI's install dir (e.g. ~/.local/bin). `-p` = headless print mode;
-      // `--force` clears the workspace-trust / tool-approval prompts that would
-      // otherwise hang a non-interactive spawn.
-      const cmd = `${agentBin} -p --force`;
-      env.REFINE_AGENT_CMD = cmd;
-      log(`✓ LLM path wired: relay will spawn  ${cmd}`);
+  const resolved = resolveAgent({ wantLlm, forceKey });
+  if (resolved.cmd) {
+    env.REFINE_AGENT_CMD = resolved.cmd;
+    if (resolved.source === "env") {
+      log(`✓ using REFINE_AGENT_CMD from environment: ${resolved.cmd}`);
+    } else {
+      const via =
+        resolved.source === "host" ? `detected ${resolved.agent.label}`
+        : resolved.source === "forced" ? `forced ${resolved.agent.label}`
+        : resolved.source === "scan" ? `found ${resolved.agent.label}`
+        : `installed ${resolved.agent.label}`;
+      log(`✓ LLM path wired (${via}): relay will spawn  ${resolved.cmd}`);
     }
+  } else if (resolved.reason) {
+    log(`• LLM not wired — ${resolved.reason}.`);
   }
 
   // 3) start the relay (foreground; Ctrl-C stops it + reverts the injection)
@@ -215,6 +319,7 @@ function cmdLive(args) {
   });
 
   const llmWired = Boolean(env.REFINE_AGENT_CMD);
+  const authHint = resolved.agent && resolved.agent.auth;
   log("");
   log("Next:");
   log("  1. Open your app — the timeline panel is now on the page.");
@@ -222,17 +327,12 @@ function cmdLive(args) {
   if (llmWired) {
     log("  3. LLM suggestions are ON — the relay runs the agent CLI per click,");
     log("     so you never have to run /refine live.");
-    log("     One-time: make sure the CLI is authenticated —");
-    log("       run `cursor-agent` once to log in, or set CURSOR_API_KEY.");
-  } else if (wantLlm) {
-    log("  3. LLM was requested but cursor-agent isn't available (install failed).");
-    log("     Install it manually, then re-run:");
-    log("       curl https://cursor.com/install -fsS | bash");
-    log("     …or run /refine live in your editor for the in-IDE-agent path.");
+    if (authHint) log(`     One-time: make sure the CLI is authenticated — ${authHint}.`);
   } else {
-    log("  3. For persistent LLM (no /refine live needed), re-run with --llm");
-    log("     (installs the Cursor CLI once). Or run /refine live in your editor");
-    log("     to use the in-IDE agent.");
+    log("  3. No agent CLI wired, so LLM features need a live answerer. Either:");
+    log("     • run /refine live in your editor (Cursor / Claude Code / Codex), or");
+    log("     • re-run with --llm to install the Cursor CLI, or");
+    log("     • export REFINE_AGENT_CMD='<your agent CLI>' and re-run.");
   }
   log("");
   log("Press Ctrl-C to stop the relay and remove the injected tag.");
@@ -274,12 +374,21 @@ function main() {
   if (cmd === "live") return cmdLive(args);
   if (cmd === "stop") return cmdStop(args);
   log("Refine — transitions.dev live tool");
-  log("  npx transitions-refine live         # inject panel + start relay");
-  log("  npx transitions-refine live --llm   # + install/wire cursor-agent for persistent LLM");
-  log("  npx transitions-refine stop         # remove the injected tag");
+  log("  npx transitions-refine live                 # inject panel + relay; auto-wire your agent CLI");
+  log("  npx transitions-refine live --agent claude  # force an agent: cursor | claude | codex");
+  log("  npx transitions-refine live --llm           # install the Cursor CLI if no agent is found");
+  log("  npx transitions-refine stop                 # remove the injected tag");
   log("");
-  log("Options: --page <html>  --port <n>  --llm (enable persistent LLM via the Cursor CLI)");
+  log("Options: --page <html>  --port <n>  --agent <cursor|claude|codex>  --llm");
+  log("It prefers the agent hosting this run (Cursor/Claude Code/Codex) so Refine uses");
+  log("the subscription you already have. Or set REFINE_AGENT_CMD to wire any CLI.");
   process.exit(cmd ? 1 : 0);
 }
 
-main();
+// Run only when invoked as the CLI entry (npx / node bin/cli.mjs), so tests can
+// import the resolver helpers without triggering a live run.
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main();
+}
+
+export { AGENTS, HOST_PRECEDENCE, detectHostAgent, resolveAgent, findBin };