Quick start

Add Hover to a project you already have running. One command, one config edit, then pnpm dev like usual.

Prerequisites

A Vite / Astro / Nuxt / Next.js / Webpack project — any framework Hover supports.
Node 22+ on PATH.
Any supported coding-agent CLI on PATH — claude, codex, cursor-agent, aider, gemini-cli, or qwen-code. Hover spawns whichever you already have. No new API keys.

Don't have an agent CLI yet?

Claude Code — npm install -g @anthropic-ai/claude-code, then claude login. Uses the Claude Pro / Max subscription you might already pay for.
OpenAI Codex — npm install -g @openai/codex, then codex login.

Either works. You can switch from the widget header any time.

Install

Run inside your project root:

npx @hover-dev/cli setup

That command:

Reads your package.json and detects your bundler.
Installs the right Hover integration package.
AST-edits your bundler config (vite.config.ts, astro.config.mjs, nuxt.config.ts, next.config.ts, or webpack.config.js) to register the plugin.
Is idempotent — running it twice is a no-op.

Monorepo (turbo / pnpm-workspace / yarn workspaces)

Run from the repo root. If one workspace declares a bundler the CLI installs there automatically; if several do, an interactive picker (↑/↓, Enter) appears. Or target an app directly: npx @hover-dev/cli setup --cwd apps/web. See Monorepos for the full breakdown.

Next.js

The CLI handles next.config.* and instrumentation.ts for you, then prints one final line to paste into app/layout.tsx — <HoverScript /> inside <body>. Works on Next 15 + 16, with Turbopack or webpack, any of .ts / .mjs / .js configs.

Prefer to do it by hand? See the manual install per bundler.

Start your dev server

Use whatever command you already use:

pnpm dev          # or `npm run dev`, `yarn dev`, `bun dev`

Hover starts a local service on 127.0.0.1:51789 and injects a floating widget (Shadow DOM, marked data-hover="true") into your dev page. The widget connects on its own.

First-run debug Chrome

On first ✨ click, the widget prompts you to launch an isolated debug Chrome on port 9222 (separate from your everyday browser — a clean profile under <tmpdir>/hover-chrome). Click the prompt and a debug Chrome opens, navigated to your dev URL. Subsequent runs reuse it.

Want it to pre-warm at dev-server boot? Pass autoLaunchChrome: true to the plugin. Note: this still launches the isolated debug Chrome — not your everyday browser. Hover never touches your normal Chrome session. See Plugin options.

Send your first prompt

Click the ✨ launcher in the corner of the page. Type, or hold the 🎙 button and speak:

log in, then add a todo named "verify hover"

Press ↵ or Send. The agent drives the debug Chrome, narrates each tool call, and renders a Result + Findings card when done.

Save the session

Click Save as Spec on the Result card. The verified flow becomes a __vibe_tests__/<slug>.spec.ts file — plain @playwright/test code that runs in your CI with no Hover dependency.

That's the loop: speak / type → agent verifies → crystallize once → CI replays forever.

The `hover` CLI

Beyond setup, everything runs through the hover bin (npx @hover-dev/cli <command>):

Command	What it does
`setup`	Detect your bundler + package manager, install the integration, wire the config
`run "<prompt>"`	Drive the debug Chrome from the terminal — no widget; `--save <slug>` crystallizes a spec
`optimize <spec>`	Optional AI pass → an improved spec candidate (diff, original kept)
`extract`	Lift flows repeated across specs into shared Page Objects + fixtures
`re-record <spec>`	Regenerate a spec against the current UI

run is CLI-only authoring (no widget — needs just @hover-dev/core); the rest post-process saved specs. Full reference: CLI.

What's next

Your first session — A guided walkthrough of every widget control on a real flow.
Pick an agent — Differences between Claude and Codex, and how to add others.
Security testing — Probe your dev app for authz / authn / parameter-tampering issues, then crystallize findings as regression specs.
Voice mode — Push-to-talk speech in 中文 / English, browser-native, no API keys.