diff --git a/CLAUDE.md b/CLAUDE.md
index 761c951..32c5f04 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -25,7 +25,7 @@ twd-relay is a WebSocket relay that lets AI agents and external tools trigger an
 
 **Browser Client** (`src/browser/`, exported as `twd-relay/browser`) — Runs in the browser. Connects to the relay, listens for commands, dynamically imports `twd-js/runner` to execute tests, and streams results back. Uses native browser `WebSocket` with auto-reconnect. Reads test state from `window.__TWD_STATE__` (set by twd-js). A small `faviconManager` (in `src/browser/faviconManager.ts`) sets a colored favicon + `document.title` prefix based on connection/run state so the active TWD tab is identifiable among multiple tabs to the same origin. A sibling `runMonitor` (in `src/browser/runMonitor.ts`) tracks per-test wall-clock time; on the 3 s heartbeat tick AND at the end of every test, the browser checks whether the test exceeded `maxTestDurationMs` (default 10 s) and, if so, emits a `run:aborted` event so the CLI can exit with a clear error instead of hanging on a throttled tab.
 
-**Vite Plugin** (`src/vite/`, exported as `twd-relay/vite`) — A Vite plugin that hooks into `configureServer` to attach the relay to the dev server's HTTP instance.
+**Vite Plugin** (`src/vite/`, exported as `twd-relay/vite`) — A Vite plugin that hooks into `configureServer` to attach the relay to the dev server's HTTP instance, and (in `apply: 'serve'` mode) auto-injects a `<script type="module">` that imports `createBrowserClient` and calls `.connect()` via a virtual module (`virtual:twd-relay/connect`). Auto-injection is on by default; set `autoConnect: false` to opt out and wire `createBrowserClient` manually (required for non-Vite consumers). Both the relay-server path and the injected client path use the same formula (`options.path ?? base + '/__twd/ws'`); `configResolved` sets the `base` for both.
 
 **CLI** (`src/cli/`, bin: `twd-relay`) — Two subcommands: `serve` (default) starts a standalone HTTP server with the relay on port 9876; `run` connects to an existing relay as a client, sends a `run` command, streams test output, and exits with code 0/1 based on results. The `run` subcommand defaults to port 5173 (Vite dev server) and has a 180s timeout. Use `--test "name"` (repeatable) to filter tests by name substring match.
 
diff --git a/README.md b/README.md
index 0915bc5..284fbb6 100644
--- a/README.md
+++ b/README.md
@@ -115,9 +115,9 @@ Change the URL if your relay uses another port or path.
 
 ## Vite plugin (optional)
 
-If you use Vite, you can attach the relay to the dev server so the WebSocket is on the same host/port:
+If you use Vite, the plugin attaches the relay to the dev server **and** auto-injects the browser client into your `index.html` — so you don't need to call `createBrowserClient` yourself:
 
-```js
+```ts
 // vite.config.ts
 import { twdRemote } from 'twd-relay/vite';
 
@@ -126,7 +126,18 @@ export default defineConfig({
 });
 ```
 
-Then in your app you can omit the URL; the client defaults to `ws(s)://<current host>/__twd/ws`.
+That's the whole setup. The plugin only runs in dev (`apply: 'serve'`); production builds are untouched.
+
+### Plugin options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `path` | `string` | `'/__twd/ws'` (relative to Vite `base`) | WebSocket path. Used both by the relay and by the injected client — single source of truth. |
+| `autoConnect` | `boolean \| AutoConnectOptions` | `true` | Inject the browser client connect script into `index.html`. Set to `false` to wire `createBrowserClient` manually in your entry file. Pass an object to forward options (`reconnect`, `reconnectInterval`, `log`, `maxTestDurationMs`) into the injected `createBrowserClient` call. |
+
+### Manual usage (non-Vite, or opting out)
+
+`twd-relay/browser` is the supported public API for any setup the Vite plugin doesn't cover (Webpack, Angular, Rollup, esbuild, Rspack), and for advanced Vite users who want to subscribe to client events or coordinate connect timing. See the [Quick start](#quick-start-standalone-relay) section above for the manual snippet. To use the manual snippet **with** the Vite plugin, set `autoConnect: false` so the plugin doesn't also inject one — otherwise two clients connect.
 
 ---
 
diff --git a/docs/superpowers/plans/2026-05-08-relay-auto-connect.md b/docs/superpowers/plans/2026-05-08-relay-auto-connect.md
new file mode 100644
index 0000000..5bae130
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-08-relay-auto-connect.md
@@ -0,0 +1,494 @@
+# Auto-Inject Browser Client — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Extend the `twdRemote()` Vite plugin so it auto-injects a `<script type="module">` into the dev-server HTML that calls `createBrowserClient(...).connect()`, eliminating the manual `main.tsx` snippet for Vite consumers. Manual `createBrowserClient` API stays untouched and remains the path for non-Vite consumers.
+
+**Architecture:** All plugin changes in `src/vite/twdRemote.ts`. The plugin claims a virtual module id (`virtual:twd-relay/connect`), `load()`s it as a small JS string that imports `createBrowserClient` from `twd-relay/browser` and connects, and injects a script tag pointing at it via `transformIndexHtml`. The relay-server path and the injected client path are computed once in `configResolved` (single source of truth). The plugin sets `apply: 'serve'` so it's inert in production builds. Auto-connect is on by default; `autoConnect: false` (or an options object for forwarded flags) is the escape hatch.
+
+**Tech Stack:** TypeScript, Vite plugin API, Vitest. Spec: `docs/superpowers/specs/2026-05-08-relay-auto-connect-design.md`.
+
+---
+
+## File Structure
+
+| File | Change |
+|---|---|
+| `src/vite/twdRemote.ts` | Extend `TwdRemoteOptions` with `autoConnect`. Add `AutoConnectOptions` interface. Extend the inline `VitePlugin` interface with `apply`, `resolveId`, `load`, `transformIndexHtml`. Move path resolution into `configResolved`. Implement the three new hooks. |
+| `src/vite/index.ts` | Re-export `AutoConnectOptions`. |
+| `src/tests/vite/twdRemote.spec.ts` | **Add** unit tests for the new behavior (current tests stay; we're extending). Use the existing `portCounter`/HTTP-server pattern only for the relay-attach tests; the new hook tests are pure (no server needed). |
+| `examples/twd-test-app/src/main.tsx` | Delete the manual `createBrowserClient` block (lines 28–32 currently). The Vue example has no such block; do not touch. |
+| `README.md` | Update `## Vite plugin (optional)` to mention auto-connect default + `autoConnect: false`. Promote the existing "Quick start (standalone relay)" snippet as the canonical "Manual usage (non-Vite)" reference. |
+| `CLAUDE.md` | One sentence under the existing relay/Vite section noting auto-connect-on-by-default and the `autoConnect: false` opt-out. |
+
+The `VitePlugin` interface stays inline (per project CLAUDE.md: "Vite plugin uses inline `VitePlugin` interface instead of importing from `vite` to avoid dts resolution issues with optional peer deps").
+
+---
+
+## Task 1: Add failing tests for the new plugin hooks
+
+**Files:**
+- Modify: `src/tests/vite/twdRemote.spec.ts` (extend existing file)
+
+**Why TDD:** The new behavior is plugin-shape changes (return values from `transformIndexHtml`, content of `load()` strings, gating on `autoConnect: false`). Pure unit-level assertions on the plugin object catch regressions cheaply and don't need a running HTTP server.
+
+- [ ] **Step 1: Add a second `describe` block at the bottom of `src/tests/vite/twdRemote.spec.ts`**
+
+Add the following after the existing `describe('twdRemote Vite plugin', ...)` block (do not modify the existing block). This new block tests the auto-connect hooks in isolation, no HTTP server needed:
+
+```typescript
+describe('twdRemote auto-connect', () => {
+  const VIRTUAL_ID = 'virtual:twd-relay/connect';
+  const RESOLVED_ID = `\0${VIRTUAL_ID}`;
+
+  function withResolvedConfig(
+    plugin: ReturnType<typeof twdRemote>,
+    base = '/',
+  ): void {
+    (plugin.configResolved as (c: { base: string }) => void)({ base });
+  }
+
+  it('injects a script tag pointing at the virtual id by default', () => {
+    const plugin = twdRemote();
+    withResolvedConfig(plugin);
+
+    const tags =
+      (plugin.transformIndexHtml as () => Array<{
+        tag: string;
+        attrs?: Record<string, string>;
+        injectTo?: string;
+      }>)();
+
+    expect(tags).toHaveLength(1);
+    const [tag] = tags;
+    expect(tag.tag).toBe('script');
+    expect(tag.attrs?.type).toBe('module');
+    expect(tag.attrs?.src).toBe(`/@id/${VIRTUAL_ID}`);
+    expect(tag.injectTo).toBe('head');
+  });
+
+  it('respects a non-default Vite base when constructing the script src', () => {
+    const plugin = twdRemote();
+    withResolvedConfig(plugin, '/my-app/');
+
+    const tags =
+      (plugin.transformIndexHtml as () => Array<{
+        attrs?: Record<string, string>;
+      }>)();
+
+    expect(tags[0].attrs?.src).toBe(`/my-app/@id/${VIRTUAL_ID}`);
+  });
+
+  it('resolveId claims the virtual id and returns the prefixed form', () => {
+    const plugin = twdRemote();
+    const resolveId = plugin.resolveId as (id: string) => string | null;
+
+    expect(resolveId(VIRTUAL_ID)).toBe(RESOLVED_ID);
+    expect(resolveId('some-other-id')).toBeNull();
+  });
+
+  it('load() returns a module that imports createBrowserClient and connects on the configured path', () => {
+    const plugin = twdRemote();
+    withResolvedConfig(plugin);
+
+    const code = (plugin.load as (id: string) => string | null)(RESOLVED_ID);
+
+    expect(code).not.toBeNull();
+    expect(code).toContain("from 'twd-relay/browser'");
+    expect(code).toContain('createBrowserClient(');
+    expect(code).toContain('.connect()');
+    expect(code).toContain('"path":"/__twd/ws"');
+  });
+
+  it('load() reflects an explicit path option', () => {
+    const plugin = twdRemote({ path: '/custom/relay' });
+    withResolvedConfig(plugin);
+
+    const code = (plugin.load as (id: string) => string | null)(RESOLVED_ID);
+
+    expect(code).toContain('"path":"/custom/relay"');
+  });
+
+  it('load() reflects a non-default Vite base', () => {
+    const plugin = twdRemote();
+    withResolvedConfig(plugin, '/my-app/');
+
+    const code = (plugin.load as (id: string) => string | null)(RESOLVED_ID);
+
+    expect(code).toContain('"path":"/my-app/__twd/ws"');
+  });
+
+  it('load() forwards AutoConnectOptions into the createBrowserClient call', () => {
+    const plugin = twdRemote({
+      autoConnect: { reconnect: false, log: true, maxTestDurationMs: 5000 },
+    });
+    withResolvedConfig(plugin);
+
+    const code = (plugin.load as (id: string) => string | null)(RESOLVED_ID);
+
+    expect(code).toContain('"reconnect":false');
+    expect(code).toContain('"log":true');
+    expect(code).toContain('"maxTestDurationMs":5000');
+  });
+
+  it('autoConnect: false makes resolveId, load, and transformIndexHtml no-ops', () => {
+    const plugin = twdRemote({ autoConnect: false });
+    withResolvedConfig(plugin);
+
+    expect(
+      (plugin.resolveId as (id: string) => string | null)(VIRTUAL_ID),
+    ).toBeNull();
+    expect((plugin.load as (id: string) => string | null)(RESOLVED_ID)).toBeNull();
+    expect((plugin.transformIndexHtml as () => unknown)()).toBeUndefined();
+  });
+
+  it('plugin opts out of production builds via apply: "serve"', () => {
+    const plugin = twdRemote();
+    expect(plugin.apply).toBe('serve');
+  });
+});
+```
+
+- [ ] **Step 2: Run the file, confirm new tests fail**
+
+Run: `npx vitest run src/tests/vite/twdRemote.spec.ts`
+
+Expected: existing 6 tests pass; the 9 new tests fail because `resolveId`, `load`, `transformIndexHtml`, and `apply` don't exist on the current plugin (or fail because `as Function` calls hit `undefined`). Failures should be type/property errors, not unrelated infrastructure errors.
+
+- [ ] **Step 3: Commit the failing tests**
+
+```bash
+git add src/tests/vite/twdRemote.spec.ts
+git commit -m "test: add failing tests for twdRemote auto-connect hooks"
+```
+
+---
+
+## Task 2: Implement the auto-connect hooks
+
+**Files:**
+- Modify: `src/vite/twdRemote.ts`
+- Modify: `src/vite/index.ts`
+
+- [ ] **Step 1: Replace `src/vite/twdRemote.ts` with the new implementation**
+
+Open `src/vite/twdRemote.ts` and replace its entire contents with:
+
+```typescript
+import { createTwdRelay } from '../relay';
+import type { Server } from 'http';
+
+export interface TwdRemoteOptions {
+  /** WebSocket path. Default: '/__twd/ws' (relative to Vite `base`). */
+  path?: string;
+
+  /**
+   * Auto-inject the browser client connect script into index.html in dev.
+   * Set to `false` to opt out (e.g. when wiring `createBrowserClient`
+   * manually in your entry file).
+   *
+   * Pass an object to forward options to the injected `createBrowserClient`
+   * call. Useful overrides: `reconnect`, `reconnectInterval`, `log`,
+   * `maxTestDurationMs`.
+   *
+   * Default: `true` (auto-connect with default client options).
+   */
+  autoConnect?: boolean | AutoConnectOptions;
+}
+
+export interface AutoConnectOptions {
+  /** See `BrowserClientOptions.reconnect`. */
+  reconnect?: boolean;
+  /** See `BrowserClientOptions.reconnectInterval`. */
+  reconnectInterval?: number;
+  /** See `BrowserClientOptions.log`. */
+  log?: boolean;
+  /** See `BrowserClientOptions.maxTestDurationMs`. */
+  maxTestDurationMs?: number;
+}
+
+interface HtmlTagDescriptor {
+  tag: string;
+  attrs?: Record<string, string>;
+  injectTo?: 'head' | 'body' | 'head-prepend' | 'body-prepend';
+}
+
+interface VitePlugin {
+  name: string;
+  apply?: 'serve' | 'build';
+  configResolved?: (config: { base: string }) => void;
+  configureServer?: (server: { httpServer: Server | null }) => void;
+  resolveId?: (id: string) => string | null;
+  load?: (id: string) => string | null;
+  transformIndexHtml?: () => HtmlTagDescriptor[] | undefined;
+}
+
+const VIRTUAL_ID = 'virtual:twd-relay/connect';
+const RESOLVED_ID = `\0${VIRTUAL_ID}`;
+
+export function twdRemote(options?: TwdRemoteOptions): VitePlugin {
+  let resolvedBase = '/';
+  let resolvedPath = '/__twd/ws';
+
+  const autoConnectEnabled = options?.autoConnect !== false;
+  const autoConnectOptions: AutoConnectOptions =
+    typeof options?.autoConnect === 'object' && options.autoConnect !== null
+      ? options.autoConnect
+      : {};
+
+  return {
+    name: 'twd-relay',
+    apply: 'serve',
+    configResolved(config) {
+      resolvedBase = config.base;
+      resolvedPath =
+        options?.path ?? resolvedBase.replace(/\/$/, '') + '/__twd/ws';
+    },
+    configureServer(server) {
+      if (!server.httpServer) return;
+      const relay = createTwdRelay(server.httpServer, { path: resolvedPath });
+      server.httpServer.on('close', () => relay.close());
+    },
+    resolveId(id) {
+      if (!autoConnectEnabled) return null;
+      return id === VIRTUAL_ID ? RESOLVED_ID : null;
+    },
+    load(id) {
+      if (!autoConnectEnabled || id !== RESOLVED_ID) return null;
+      const opts = JSON.stringify({ path: resolvedPath, ...autoConnectOptions });
+      return [
+        "import { createBrowserClient } from 'twd-relay/browser';",
+        `createBrowserClient(${opts}).connect();`,
+      ].join('\n');
+    },
+    transformIndexHtml() {
+      if (!autoConnectEnabled) return undefined;
+      return [
+        {
+          tag: 'script',
+          attrs: {
+            type: 'module',
+            src: `${resolvedBase}@id/${VIRTUAL_ID}`,
+          },
+          injectTo: 'head',
+        },
+      ];
+    },
+  };
+}
+```
+
+Key things to notice (and verify against the diff once written):
+
+- `configResolved` now also computes `resolvedPath`. `configureServer` reads it. The relay-server path and the injected client path agree by construction.
+- `apply: 'serve'` keeps the plugin inert in production builds.
+- The `HtmlTagDescriptor` interface is inline (matches the project's "no `vite` import" decision).
+- `resolveId`/`load`/`transformIndexHtml` short-circuit when `autoConnectEnabled` is `false`. The relay-server attach in `configureServer` is unaffected by the toggle.
+
+- [ ] **Step 2: Update `src/vite/index.ts` to export `AutoConnectOptions`**
+
+Replace its contents with:
+
+```typescript
+export { twdRemote } from './twdRemote';
+export type { TwdRemoteOptions, AutoConnectOptions } from './twdRemote';
+```
+
+- [ ] **Step 3: Run the vite test file, confirm all tests pass**
+
+Run: `npx vitest run src/tests/vite/twdRemote.spec.ts`
+
+Expected: all 15 tests pass (6 existing + 9 new).
+
+- [ ] **Step 4: Run the full suite, confirm no regressions**
+
+Run: `npm test -- --run`
+
+Expected: every existing test still passes, plus the new ones. No `EADDRINUSE`, no flake. The CLI test, browser tests, relay tests, and heartbeat tests are independent of the vite plugin and should be unaffected.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/vite/twdRemote.ts src/vite/index.ts
+git commit -m "feat(vite): auto-inject browser client connect script in dev"
+```
+
+---
+
+## Task 3: Remove the manual `createBrowserClient` block from the React example
+
+**Files:**
+- Modify: `examples/twd-test-app/src/main.tsx:28-32`
+
+This proves the new plugin behavior end-to-end and matches the spec's recommended migration. The Vue example (`examples/vue-twd-example`) has no such block (verified via grep) — leave it alone.
+
+- [ ] **Step 1: Delete the manual block**
+
+In `examples/twd-test-app/src/main.tsx`, the current dev-only `if (import.meta.env.DEV) { ... }` body ends with these five lines:
+
+```tsx
+  // Browser client: connects to the relay via the Vite plugin.
+  // To trigger a run: npx twd-relay run (or node ../../dist/cli.js run)
+  const { createBrowserClient } = await import('twd-relay/browser');
+  const client = createBrowserClient();
+  client.connect();
+```
+
+Delete those five lines (and the blank line preceding the comment if any). Leave the rest of the dev block (test-modules import, `initTests`, `twd.initRequestMocking()`) intact — those are twd-js setup, not relay setup.
+
+After the edit, the tail of the dev block should look like:
+
+```tsx
+  twd.initRequestMocking()
+    .then(() => {
+      console.log("Request mocking initialized");
+    })
+    .catch((err) => {
+      console.error("Error initializing request mocking:", err);
+    });
+}
+```
+
+- [ ] **Step 2: Manually verify the example still loads and connects**
+
+This is the only manual smoke needed. From the repo root:
+
+```bash
+npm run build
+cd examples/twd-test-app
+npm run dev
+```
+
+In the browser, open the printed URL and confirm:
+
+1. The page renders normally (no JS errors in DevTools console).
+2. DevTools → Network → WS shows a connection to `/__twd/ws`.
+3. The `[TWD]` title prefix appears in the tab title (set by the browser client's favicon manager once connected).
+4. From another terminal: `npx twd-relay run --port <vite-port>` — tests should run.
+
+If any of these fail, STOP and report. Do not commit.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add examples/twd-test-app/src/main.tsx
+git commit -m "chore(example): rely on twdRemote auto-connect in test-app"
+```
+
+---
+
+## Task 4: Update README
+
+**Files:**
+- Modify: `README.md` — `## Vite plugin (optional)` section starting at line 116.
+
+- [ ] **Step 1: Replace the Vite plugin section body**
+
+Find the section that currently reads:
+
+```markdown
+## Vite plugin (optional)
+
+If you use Vite, you can attach the relay to the dev server so the WebSocket is on the same host/port:
+
+```js
+// vite.config.ts
+import { twdRemote } from 'twd-relay/vite';
+
+export default defineConfig({
+  plugins: [react(), twdRemote()],
+});
+```
+
+Then in your app you can omit the URL; the client defaults to `ws(s)://<current host>/__twd/ws`.
+```
+
+Replace the body (everything between the `## Vite plugin (optional)` header and the next `---` separator) with:
+
+```markdown
+## Vite plugin (optional)
+
+If you use Vite, the plugin attaches the relay to the dev server **and** auto-injects the browser client into your `index.html` — so you don't need to call `createBrowserClient` yourself:
+
+```ts
+// vite.config.ts
+import { twdRemote } from 'twd-relay/vite';
+
+export default defineConfig({
+  plugins: [react(), twdRemote()],
+});
+```
+
+That's the whole setup. The plugin only runs in dev (`apply: 'serve'`); production builds are untouched.
+
+### Plugin options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `path` | `string` | `'/__twd/ws'` (relative to Vite `base`) | WebSocket path. Used both by the relay and by the injected client — single source of truth. |
+| `autoConnect` | `boolean \| AutoConnectOptions` | `true` | Inject the browser client connect script into `index.html`. Set to `false` to wire `createBrowserClient` manually in your entry file. Pass an object to forward options (`reconnect`, `reconnectInterval`, `log`, `maxTestDurationMs`) into the injected `createBrowserClient` call. |
+
+### Manual usage (non-Vite, or opting out)
+
+`twd-relay/browser` is the supported public API for any setup the Vite plugin doesn't cover (Webpack, Angular, Rollup, esbuild, Rspack), and for advanced Vite users who want to subscribe to client events or coordinate connect timing. See the [Quick start](#quick-start-standalone-relay) section above for the manual snippet. To use the manual snippet **with** the Vite plugin, set `autoConnect: false` so the plugin doesn't also inject one — otherwise two clients connect.
+```
+
+(The `[Quick start](#quick-start-standalone-relay)` link points to the existing section; verify the anchor by GitHub-rendered slug rules — lower-cased, spaces → hyphens, parentheses dropped.)
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: document twdRemote auto-connect option"
+```
+
+---
+
+## Task 5: Update project CLAUDE.md
+
+**Files:**
+- Modify: `CLAUDE.md` — the bullet covering the Vite plugin in the Architecture section.
+
+- [ ] **Step 1: Update the Vite plugin bullet**
+
+Open `CLAUDE.md` (the project-root `CLAUDE.md` for `twd-relay`) and locate the Architecture-section paragraph that begins:
+
+```
+**Vite Plugin** (`src/vite/`, exported as `twd-relay/vite`) — A Vite plugin that hooks into `configureServer` to attach the relay to the dev server's HTTP instance.
+```
+
+Replace that whole paragraph with:
+
+```
+**Vite Plugin** (`src/vite/`, exported as `twd-relay/vite`) — A Vite plugin that hooks into `configureServer` to attach the relay to the dev server's HTTP instance, and (in `apply: 'serve'` mode) auto-injects a `<script type="module">` that imports `createBrowserClient` and calls `.connect()` via a virtual module (`virtual:twd-relay/connect`). Auto-injection is on by default; set `autoConnect: false` to opt out and wire `createBrowserClient` manually (required for non-Vite consumers). The relay-server path and the injected client path are computed once in `configResolved` so they cannot drift.
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add CLAUDE.md
+git commit -m "docs(claude): note auto-connect default in vite plugin section"
+```
+
+---
+
+## Out of Scope (per spec)
+
+- Removing or deprecating `createBrowserClient`. Stays public.
+- Plugins for Webpack/Rollup/Angular/Rspack. Manual API serves them.
+- Coordinating injected connect with React mount timing (fire-and-forget is sufficient).
+- Surfacing client events through plugin options.
+- A URL builder fn in place of the `path` option.
+- Auto-detecting whether the user already calls `createBrowserClient` manually. Changelog covers this in the migration note.
+- Version bump / publish — handled separately on `main`.
+
+---
+
+## Manual smoke summary (covered in Task 3 Step 2)
+
+1. Build the package: `npm run build`.
+2. Run the React example: `cd examples/twd-test-app && npm run dev`.
+3. Confirm: page renders, WS connection in DevTools, `[TWD]` title prefix, `npx twd-relay run` triggers a real run.
+4. Confirm: with `autoConnect: false` in `vite.config.ts` and the manual block restored in `main.tsx`, behavior is identical to today (one client). Then revert.
+
+The unit tests cover the plugin shape; the manual smoke covers the integration end-to-end.
diff --git a/docs/superpowers/specs/2026-05-08-relay-auto-connect-design.md b/docs/superpowers/specs/2026-05-08-relay-auto-connect-design.md
new file mode 100644
index 0000000..1a655f1
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-08-relay-auto-connect-design.md
@@ -0,0 +1,226 @@
+# Auto-Inject Browser Client Connect via `twdRemote()` Plugin
+
+## Problem
+
+Today, wiring up `twd-relay` in a Vite project takes two coordinated changes:
+
+1. Add `twdRemote()` to `vite.config.ts` (starts the relay WebSocket server).
+2. Add a dev-only block to the entry file (`main.tsx` / `main.ts`) that imports `createBrowserClient` and calls `.connect()`:
+
+```ts
+if (import.meta.env.DEV) {
+  const { createBrowserClient } = await import('twd-relay/browser');
+  const client = createBrowserClient({
+    url: `${window.location.origin}/__twd/ws`,
+  });
+  client.connect();
+}
+```
+
+This is awkward for three reasons:
+
+- **Two places to keep in sync.** If the plugin's `path` option changes, the entry-file `url` has to change too. There is no single source of truth for "where is the relay listening."
+- **Dev-only cruft in app code.** The block lives next to `ReactDOM.createRoot(...)` even though it has nothing to do with the app. Authors who haven't seen it before reasonably wonder why their entry file has an `await import` and a WebSocket connect.
+- **Asymmetry with `twd-js`.** The companion `twd()` plugin (recently introduced) already auto-injects its own browser script via `transformIndexHtml`. After that migration, `main.tsx` has only the relay leftover — which now stands out as the one remaining piece of dev tooling in app code.
+
+End-state target: a Vite project using `twd-relay` should need **zero** dev-only code in its entry file. Plugin in `vite.config.ts` is the single point of configuration.
+
+## Solution
+
+Extend `twdRemote()` to also inject a `<script type="module">` into the dev-server HTML that constructs the browser client and calls `.connect()`. Same pattern `twd-js`'s `twd()` plugin uses (virtual module + `transformIndexHtml`).
+
+The injection is **on by default** because the 90% case is "I want the relay to work end-to-end." Users who need custom client behavior (custom URL, hooks into client events, integration with non-Vite bundlers) can disable it with a single option and continue using the manual `createBrowserClient` API in their entry file.
+
+## Why keep the manual API
+
+The existing `createBrowserClient` export is **not** going away. It remains the supported public API for:
+
+- **Angular / Webpack / Rollup / esbuild / Rspack consumers.** They have no Vite plugin available; the manual init is their only path. Removing it would break these projects.
+- **Advanced Vite users** who want to subscribe to client events, customize reconnect behavior beyond what plugin options expose, or coordinate connect timing with their own startup logic.
+
+The plugin auto-connect is a sugar layer on top — it imports `createBrowserClient` from the same public entry. No internal-only API, no two implementations to maintain.
+
+## Plugin API changes
+
+Extend `TwdRemoteOptions` with an `autoConnect` option that accepts `false` (off) or an options object (on, with overrides):
+
+```ts
+export interface TwdRemoteOptions {
+  /** WebSocket path. Default: '/__twd/ws' */
+  path?: string;
+
+  /**
+   * Auto-inject the browser client connect script into index.html in dev.
+   * Set to `false` to opt out (e.g. when wiring `createBrowserClient`
+   * manually in your entry file).
+   *
+   * Pass an object to forward options to the injected `createBrowserClient`
+   * call. Useful overrides: `reconnect`, `reconnectInterval`, `log`,
+   * `maxTestDurationMs`.
+   *
+   * Default: `true` (auto-connect with default client options).
+   */
+  autoConnect?: boolean | AutoConnectOptions;
+}
+
+export interface AutoConnectOptions {
+  /** See `BrowserClientOptions.reconnect`. */
+  reconnect?: boolean;
+  /** See `BrowserClientOptions.reconnectInterval`. */
+  reconnectInterval?: number;
+  /** See `BrowserClientOptions.log`. */
+  log?: boolean;
+  /** See `BrowserClientOptions.maxTestDurationMs`. */
+  maxTestDurationMs?: number;
+}
+```
+
+`url` and `path` are intentionally **not** in `AutoConnectOptions`: the plugin already knows its own path (from its own `path` option, falling back to the configured Vite `base`), and the script computes the URL at runtime from `window.location`. Forcing them apart would re-introduce the "two places to keep in sync" problem this spec exists to remove.
+
+## Implementation
+
+All changes in `src/vite/twdRemote.ts`. Plus optional extension to `src/index.ts` if a separate sub-export is needed (it is not — see "Module layout" below).
+
+### Pattern: virtual module + `transformIndexHtml`
+
+Mirror `twd-js`'s `twd()` plugin (`vite-plugin.es.js:46–73`):
+
+1. **`resolveId(id)`** — claim a virtual module name (e.g. `'virtual:twd-relay/connect'`) and return its prefixed form.
+2. **`load(id)`** — when the prefixed id is requested, return a small JS string that imports `createBrowserClient` from the public `twd-relay/browser` entry, instantiates it with the resolved options, and calls `.connect()`.
+3. **`transformIndexHtml()`** — inject a `<script type="module" src="/@id/virtual:twd-relay/connect">` tag into `<head>` so the dev server serves the virtual module on first page load.
+4. **`apply: 'serve'`** — only active in dev. Production builds are unaffected.
+
+The injected script is literally:
+
+```ts
+import { createBrowserClient } from 'twd-relay/browser';
+createBrowserClient({ path: '<resolved-path>', /* forwarded options */ }).connect();
+```
+
+`<resolved-path>` is the same path the relay is listening on, computed from `options.path ?? base + '/__twd/ws'` in `configResolved`. Single source of truth.
+
+### Sketch
+
+```ts
+const VIRTUAL_ID = 'virtual:twd-relay/connect';
+const RESOLVED_ID = `\0${VIRTUAL_ID}`;
+
+export function twdRemote(options?: TwdRemoteOptions): VitePlugin {
+  let resolvedBase = '/';
+  let resolvedPath = '/__twd/ws';
+  const autoConnect = options?.autoConnect !== false;
+  const autoConnectOptions =
+    typeof options?.autoConnect === 'object' ? options.autoConnect : {};
+
+  return {
+    name: 'twd-relay',
+    apply: 'serve',
+    configResolved(config) {
+      resolvedBase = config.base;
+      resolvedPath = options?.path ?? resolvedBase.replace(/\/$/, '') + '/__twd/ws';
+    },
+    configureServer(server) {
+      if (!server.httpServer) return;
+      const relay = createTwdRelay(server.httpServer, { path: resolvedPath });
+      server.httpServer.on('close', () => relay.close());
+    },
+    resolveId(id) {
+      if (!autoConnect) return null;
+      return id === VIRTUAL_ID ? RESOLVED_ID : null;
+    },
+    load(id) {
+      if (!autoConnect || id !== RESOLVED_ID) return null;
+      const opts = JSON.stringify({ path: resolvedPath, ...autoConnectOptions });
+      return [
+        "import { createBrowserClient } from 'twd-relay/browser';",
+        `createBrowserClient(${opts}).connect();`,
+      ].join('\n');
+    },
+    transformIndexHtml() {
+      if (!autoConnect) return;
+      return [{
+        tag: 'script',
+        attrs: {
+          type: 'module',
+          src: `${resolvedBase}@id/${VIRTUAL_ID}`,
+        },
+        injectTo: 'head',
+      }];
+    },
+  };
+}
+```
+
+### Why fire-and-forget is safe here
+
+`createBrowserClient(...).connect()` opens a WebSocket. The connection is **not** required to be established before the React app mounts — test runs are triggered later by `twd-relay run`, by which point the WS has had seconds to connect. There is no timing-sensitive await needed in app code. A separate `<script type="module">` running in parallel with `main.tsx` is fine.
+
+(Contrast: the `twd-js` plugin migration prompted a brief race-with-React-mount investigation. That investigation found no real race, and the relay case is even less coupled because the relay client doesn't touch the DOM or any global state the app reads at mount.)
+
+## Module layout
+
+No new sub-package or sub-export is needed. The injected script imports `createBrowserClient` from the existing `twd-relay/browser` entry, which is the same import path users already use manually. This means:
+
+- **Bundle size impact for plugin users:** identical to today (they were importing the same module manually anyway).
+- **No risk of duplicate clients:** the virtual module is the only injection point. If a user enables `autoConnect` *and* calls `createBrowserClient(...).connect()` manually in their entry file, two clients connect — but that's a user error visible in the relay's connection count, not a hidden footgun.
+
+The injected import path is hardcoded as the bare specifier `'twd-relay/browser'`. Vite resolves it through the consumer's `node_modules`. No path-mapping or alias gymnastics needed.
+
+## Files changed
+
+| File | Change |
+|---|---|
+| `src/vite/twdRemote.ts` | Add `autoConnect` to `TwdRemoteOptions`. Add `AutoConnectOptions` interface. Implement `resolveId` / `load` / `transformIndexHtml` for the virtual connect module. Compute `resolvedPath` in `configResolved` so the relay server and the injected script agree. Add `apply: 'serve'`. |
+| `src/vite/index.ts` | Re-export `AutoConnectOptions` if it's part of the public type surface. |
+| `src/tests/vite/twdRemote.spec.ts` (new or extended) | Test: with default options, `transformIndexHtml` returns a `<script type="module">` pointing at the virtual id; `load(RESOLVED_ID)` returns a string containing `createBrowserClient(` and the configured `path`. Test: with `autoConnect: false`, `resolveId` / `load` / `transformIndexHtml` are no-ops. Test: `autoConnect: { reconnect: false }` is forwarded into the loaded module string. |
+| `examples/` (if there's a Vite example app) | Remove the manual `createBrowserClient` block from the entry file in the example to demonstrate the new flow. Keep the manual usage documented in README under the non-Vite section. |
+| `README.md` | Document the new option. Add a clear "non-Vite usage" section that keeps the manual `createBrowserClient` example for Angular/Webpack/Rollup/Rspack consumers. Note the option to opt out (`autoConnect: false`) when manual control is needed. |
+| `CLAUDE.md` | One sentence under the existing relay section noting the auto-connect default and the `autoConnect: false` opt-out. |
+
+`src/browser/createBrowserClient.ts` and `src/browser/types.ts` are **not** changed — the public API stays identical.
+
+## Edge cases
+
+| Scenario | Behavior |
+|---|---|
+| Default Vite project | Plugin auto-injects script. App author writes nothing in `main.tsx`. Connect happens on first page load. |
+| User passes `autoConnect: false` | No virtual module, no script injection. User wires `createBrowserClient` manually in their entry file. Identical to today's behavior. |
+| User passes `autoConnect: { reconnect: false }` | Virtual module includes that option in the `createBrowserClient` call. |
+| User changes `path: '/custom/relay'` | Both the relay server and the injected script use `/custom/relay`. No drift. |
+| User runs production build | `apply: 'serve'` keeps the plugin off in build. No script injection in production HTML. |
+| User has both `autoConnect: true` AND a manual `createBrowserClient(...).connect()` in their entry file | Two clients connect. Visible in relay logs / connection count. Not a hidden bug — the user explicitly did both. README note. |
+| Vite `base` is non-default (e.g. `/app/`) | `resolvedPath` already accounts for base via the existing `configResolved` logic. Virtual module URL is `${base}@id/virtual:twd-relay/connect`. |
+| Non-Vite project (Webpack, Angular, Rollup, esbuild, Rspack) | Plugin not used. Users continue with manual `createBrowserClient`. No change. |
+| TypeScript user wants types for `autoConnect` options | `AutoConnectOptions` exported from `twd-relay/vite`. |
+| User on an older `twd-relay` upgrades and the option default changes their behavior | Default becomes `autoConnect: true`, which **adds** a behavior. If they already wired `createBrowserClient` manually, they now get two clients. Mitigation: changelog entry calling this out explicitly, with a one-line migration ("remove the manual block in `main.tsx` OR set `autoConnect: false`"). |
+
+## Migration path for existing Vite consumers
+
+After upgrade, users have three options:
+
+1. **Recommended:** delete the manual `createBrowserClient` block from `main.tsx` (or its equivalent). End state: zero dev-only code in entry file.
+2. **No-op:** set `autoConnect: false` in the plugin call. Behavior identical to before the upgrade.
+3. **Both at once is wrong** — auto-connect plus manual connect = two clients. The changelog will flag this loudly.
+
+For non-Vite consumers: nothing changes. Their manual usage is the only path and remains supported.
+
+## Testing approach
+
+**Unit-level tests on the plugin object** (existing pattern in `src/tests/vite/`):
+
+- `twdRemote()` returns a plugin where `transformIndexHtml()` yields exactly one `<script>` tag with `type="module"` and `src="/@id/virtual:twd-relay/connect"`.
+- `load('\0virtual:twd-relay/connect')` returns a string that contains `createBrowserClient` and the resolved `path`.
+- `twdRemote({ autoConnect: false })` returns a plugin where `resolveId` / `load` / `transformIndexHtml` are no-ops (return null/undefined).
+- `twdRemote({ autoConnect: { reconnect: false, log: true } })` includes `"reconnect":false` and `"log":true` in the loaded module string.
+- `twdRemote({ path: '/custom' })` produces a load output containing `"path":"/custom"`.
+
+**Integration smoke** (manual or scripted): run a real Vite example app, observe the WS connection in DevTools, run `twd-relay run` and confirm tests execute. Repeat with `autoConnect: false` and a manual `createBrowserClient` call in the entry file.
+
+## Non-goals
+
+- Removing or deprecating `createBrowserClient`. Stays public and supported. Non-Vite users depend on it.
+- Webpack / Rollup / Angular plugins. Out of scope for this change. The manual API serves them.
+- Coordinating the auto-connect with React mount timing (e.g. waiting until `DOMContentLoaded`). Fire-and-forget is sufficient — the WS connect is not on any user-interaction critical path.
+- Surfacing client events (connect, disconnect, error) through plugin options. Users who need event hooks should drop to the manual API; trying to channel arbitrary callbacks through plugin options gets ugly fast.
+- Replacing the existing `path` option with anything more elaborate (e.g. URL builder fns). The current shape is sufficient.
+- Auto-detecting whether the user already calls `createBrowserClient` manually. Not feasible from plugin context; addressed via changelog instead.
diff --git a/examples/twd-test-app/src/main.tsx b/examples/twd-test-app/src/main.tsx
index b5cd904..a21e3a5 100644
--- a/examples/twd-test-app/src/main.tsx
+++ b/examples/twd-test-app/src/main.tsx
@@ -25,11 +25,6 @@ if (import.meta.env.DEV) {
     .catch((err) => {
       console.error("Error initializing request mocking:", err);
     });
-  // Browser client: connects to the relay via the Vite plugin.
-  // To trigger a run: npx twd-relay run (or node ../../dist/cli.js run)
-  const { createBrowserClient } = await import('twd-relay/browser');
-  const client = createBrowserClient();
-  client.connect();
 }
 
 createRoot(document.getElementById('root')!).render(
diff --git a/src/tests/vite/twdRemote.spec.ts b/src/tests/vite/twdRemote.spec.ts
index 6f6594e..958fd4c 100644
--- a/src/tests/vite/twdRemote.spec.ts
+++ b/src/tests/vite/twdRemote.spec.ts
@@ -138,3 +138,114 @@ describe('twdRemote Vite plugin', () => {
     await new Promise((resolve) => setTimeout(resolve, 50));
   });
 });
+
+describe('twdRemote auto-connect', () => {
+  const VIRTUAL_ID = 'virtual:twd-relay/connect';
+  const RESOLVED_ID = `\0${VIRTUAL_ID}`;
+
+  function withResolvedConfig(
+    plugin: ReturnType<typeof twdRemote>,
+    base = '/',
+  ): void {
+    (plugin.configResolved as (c: { base: string }) => void)({ base });
+  }
+
+  it('injects a script tag pointing at the virtual id by default', () => {
+    const plugin = twdRemote();
+    withResolvedConfig(plugin);
+
+    const tags =
+      (plugin.transformIndexHtml as () => Array<{
+        tag: string;
+        attrs?: Record<string, string>;
+        injectTo?: string;
+      }>)();
+
+    expect(tags).toHaveLength(1);
+    const [tag] = tags;
+    expect(tag.tag).toBe('script');
+    expect(tag.attrs?.type).toBe('module');
+    expect(tag.attrs?.src).toBe(`/@id/${VIRTUAL_ID}`);
+    expect(tag.injectTo).toBe('head');
+  });
+
+  it('respects a non-default Vite base when constructing the script src', () => {
+    const plugin = twdRemote();
+    withResolvedConfig(plugin, '/my-app/');
+
+    const tags =
+      (plugin.transformIndexHtml as () => Array<{
+        attrs?: Record<string, string>;
+      }>)();
+
+    expect(tags[0].attrs?.src).toBe(`/my-app/@id/${VIRTUAL_ID}`);
+  });
+
+  it('resolveId claims the virtual id and returns the prefixed form', () => {
+    const plugin = twdRemote();
+    const resolveId = plugin.resolveId as (id: string) => string | null;
+
+    expect(resolveId(VIRTUAL_ID)).toBe(RESOLVED_ID);
+    expect(resolveId('some-other-id')).toBeNull();
+  });
+
+  it('load() returns a module that imports createBrowserClient and connects on the configured path', () => {
+    const plugin = twdRemote();
+    withResolvedConfig(plugin);
+
+    const code = (plugin.load as (id: string) => string | null)(RESOLVED_ID);
+
+    expect(code).not.toBeNull();
+    expect(code).toContain("from 'twd-relay/browser'");
+    expect(code).toContain('createBrowserClient(');
+    expect(code).toContain('.connect()');
+    expect(code).toContain('"path":"/__twd/ws"');
+  });
+
+  it('load() reflects an explicit path option', () => {
+    const plugin = twdRemote({ path: '/custom/relay' });
+    withResolvedConfig(plugin);
+
+    const code = (plugin.load as (id: string) => string | null)(RESOLVED_ID);
+
+    expect(code).toContain('"path":"/custom/relay"');
+  });
+
+  it('load() reflects a non-default Vite base', () => {
+    const plugin = twdRemote();
+    withResolvedConfig(plugin, '/my-app/');
+
+    const code = (plugin.load as (id: string) => string | null)(RESOLVED_ID);
+
+    expect(code).toContain('"path":"/my-app/__twd/ws"');
+  });
+
+  it('load() forwards AutoConnectOptions into the createBrowserClient call', () => {
+    const plugin = twdRemote({
+      autoConnect: { reconnect: false, log: true, maxTestDurationMs: 5000 },
+    });
+    withResolvedConfig(plugin);
+
+    const code = (plugin.load as (id: string) => string | null)(RESOLVED_ID);
+
+    expect(code).toContain('"reconnect":false');
+    expect(code).toContain('"log":true');
+    expect(code).toContain('"maxTestDurationMs":5000');
+  });
+
+  it('autoConnect: false makes resolveId, load, and transformIndexHtml no-ops', () => {
+    const plugin = twdRemote({ autoConnect: false });
+    withResolvedConfig(plugin);
+
+    expect(
+      (plugin.resolveId as (id: string) => string | null)(VIRTUAL_ID),
+    ).toBeNull();
+    expect((plugin.load as (id: string) => string | null)(RESOLVED_ID)).toBeNull();
+    expect((plugin.transformIndexHtml as () => unknown)()).toBeUndefined();
+  });
+
+  it('plugin opts out of production builds via apply: "serve"', () => {
+    const plugin = twdRemote();
+    expect(plugin.apply).toBe('serve');
+  });
+});
diff --git a/src/vite/index.ts b/src/vite/index.ts
index 20ed158..bb45c8b 100644
--- a/src/vite/index.ts
+++ b/src/vite/index.ts
@@ -1,2 +1,2 @@
 export { twdRemote } from './twdRemote';
-export type { TwdRemoteOptions } from './twdRemote';
+export type { TwdRemoteOptions, AutoConnectOptions } from './twdRemote';
diff --git a/src/vite/twdRemote.ts b/src/vite/twdRemote.ts
index 623b4ca..d85915d 100644
--- a/src/vite/twdRemote.ts
+++ b/src/vite/twdRemote.ts
@@ -2,33 +2,102 @@ import { createTwdRelay } from '../relay';
 import type { Server } from 'http';
 
 export interface TwdRemoteOptions {
-  /** WebSocket path. Default: '/__twd/ws' */
+  /** WebSocket path. Default: '/__twd/ws' (relative to Vite `base`). */
   path?: string;
+
+  /**
+   * Auto-inject the browser client connect script into index.html in dev.
+   * Set to `false` to opt out (e.g. when wiring `createBrowserClient`
+   * manually in your entry file).
+   *
+   * Pass an object to forward options to the injected `createBrowserClient`
+   * call. Useful overrides: `reconnect`, `reconnectInterval`, `log`,
+   * `maxTestDurationMs`.
+   *
+   * Default: `true` (auto-connect with default client options).
+   */
+  autoConnect?: boolean | AutoConnectOptions;
+}
+
+export interface AutoConnectOptions {
+  /** See `BrowserClientOptions.reconnect`. */
+  reconnect?: boolean;
+  /** See `BrowserClientOptions.reconnectInterval`. */
+  reconnectInterval?: number;
+  /** See `BrowserClientOptions.log`. */
+  log?: boolean;
+  /** See `BrowserClientOptions.maxTestDurationMs`. */
+  maxTestDurationMs?: number;
+}
+
+interface HtmlTagDescriptor {
+  tag: string;
+  attrs?: Record<string, string>;
+  injectTo?: 'head' | 'body' | 'head-prepend' | 'body-prepend';
 }
 
 interface VitePlugin {
   name: string;
+  apply?: 'serve' | 'build';
   configResolved?: (config: { base: string }) => void;
   configureServer?: (server: { httpServer: Server | null }) => void;
+  resolveId?: (id: string) => string | null;
+  load?: (id: string) => string | null;
+  transformIndexHtml?: () => HtmlTagDescriptor[] | undefined;
 }
 
+const VIRTUAL_ID = 'virtual:twd-relay/connect';
+const RESOLVED_ID = `\0${VIRTUAL_ID}`;
+
 export function twdRemote(options?: TwdRemoteOptions): VitePlugin {
   let resolvedBase = '/';
+  let resolvedPath = '/__twd/ws';
+
+  const autoConnectEnabled = options?.autoConnect !== false;
+  const autoConnectOptions: AutoConnectOptions =
+    typeof options?.autoConnect === 'object' && options.autoConnect !== null
+      ? options.autoConnect
+      : {};
 
   return {
     name: 'twd-relay',
+    apply: 'serve',
     configResolved(config) {
       resolvedBase = config.base;
+      resolvedPath =
+        options?.path ?? resolvedBase.replace(/\/$/, '') + '/__twd/ws';
     },
     configureServer(server) {
       if (!server.httpServer) return;
-
       const path =
         options?.path ?? resolvedBase.replace(/\/$/, '') + '/__twd/ws';
-
       const relay = createTwdRelay(server.httpServer, { path });
-
       server.httpServer.on('close', () => relay.close());
     },
+    resolveId(id) {
+      if (!autoConnectEnabled) return null;
+      return id === VIRTUAL_ID ? RESOLVED_ID : null;
+    },
+    load(id) {
+      if (!autoConnectEnabled || id !== RESOLVED_ID) return null;
+      const opts = JSON.stringify({ path: resolvedPath, ...autoConnectOptions });
+      return [
+        "import { createBrowserClient } from 'twd-relay/browser';",
+        `createBrowserClient(${opts}).connect();`,
+      ].join('\n');
+    },
+    transformIndexHtml() {
+      if (!autoConnectEnabled) return undefined;
+      return [
+        {
+          tag: 'script',
+          attrs: {
+            type: 'module',
+            src: `${resolvedBase}@id/${VIRTUAL_ID}`,
+          },
+          injectTo: 'head',
+        },
+      ];
+    },
   };
 }