# 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.

<Callout type="tip" title="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.

</Callout>

## Install

Run inside your project root:

```bash
npx @hover-dev/cli setup
```

That command:

1. Reads your `package.json` and detects your bundler.
2. Installs the right Hover integration package.
3. 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.
4. Is idempotent — running it twice is a no-op.

<Callout type="tip" title="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](/docs/get-started/install#monorepos-turbo-pnpm-workspace-yarn-workspaces) for the full breakdown.

</Callout>

<Callout type="tip" title="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.

</Callout>

Prefer to do it by hand? See the [manual install per bundler](/docs/get-started/install#option-b-manual-install).

## Start your dev server

Use whatever command you already use:

```bash
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.

<Callout type="tip" title="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](/docs/reference/plugin-options#about-the-debug-chrome-faq).

</Callout>

## 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](/docs/reference/cli).

## What's next

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