# Quickstart

> Go from an unconfigured React app to a real widget-to-agent issue dispatch.

This tutorial proves the entire local round trip: browser → hub → one watching
agent session. You need Node.js 20+, React 18+, and an MCP-capable coding agent.

## 1. Scaffold the widget and agent

Run setup from an existing React project. Pick the coding agent you actually
use:

```bash
npx -y @wcgw/vibe-check-mcp@latest setup --agent codex --project my-storefront
```

`--agent` accepts `codex`, `claude-code`, or `cursor`. Setup detects pnpm, npm,
Yarn, or Bun; installs the matching widget; creates
`src/VibeCheckDevtools.tsx` when your project has `src/`; and configures the MCP
client. Existing Cursor servers are preserved. Use `--dry-run` to see every
action without writing or running commands.

Mount the generated component once near your app root:

```tsx
import { VibeCheckDevtools } from './VibeCheckDevtools'

export const Root = () => (
  <>
    <App />
    <VibeCheckDevtools />
  </>
)
```

Setup does not guess which app entrypoint to modify. The generated component is
the only source file it creates, and it returns `null` when
`process.env.NODE_ENV === 'production'`. Use `--force` only when you want to
replace that generated file.

**Manual equivalent**

  The scaffold performs the package install and generates the same configuration
  shown below. Continue manually when you prefer to own every line.

```bash
pnpm add -D @wcgw/vibe-check
```

```tsx
import { PerfToggle } from '@wcgw/vibe-check'

export const Root = () => {
  return (
    <>
      <App />
      {process.env.NODE_ENV !== 'production' && (
        <PerfToggle vibeCheckProps={{
          beaconUrl: 'http://127.0.0.1:4200',
          projectId: 'my-storefront',
        }} />
      )}
    </>
  )
}
```

Use a stable `projectId`, not a random value. It is the routing key that keeps
parallel dev servers separate.

## 2. Start your app and the hub

Run your normal dev command. In a second terminal, start one hub and keep it
running:

```bash
npx -y @wcgw/vibe-check-mcp@0.3.0 hub
```

Expand the widget with its pill or **Alt+Shift+V**. Its Agent tab should say
**Waiting for an agent**. That state proves the widget reached the hub.

## 3. Register the bridge

For Claude Code:

```bash
claude mcp add vibe-check -- npx -y @wcgw/vibe-check-mcp@0.3.0 connect
```

Other clients use the same spawned command:

```json
{
  "mcpServers": {
    "vibe-check": {
      "command": "npx",
      "args": ["-y", "@wcgw/vibe-check-mcp@0.3.0", "connect"]
    }
  }
}
```

Restart the agent client after changing MCP configuration. The bridge connects
to the already-running hub; it does not open another browser port.

## 4. Make one agent watch the project

Ask the agent:

```text
Call list_projects, then watch_for_issue for project my-storefront.
```

The tool call remains pending. The widget should now say **Agent connected**.
This is an exclusive lease: another agent attempting to watch `my-storefront`
is rejected and the widget shows a conflict warning.

## 5. Click Send to agent

Wait for any issue to appear, expand it, and click **Send to agent**. You can do
this from **Agent**, **SEO**, **AEO**, or an on-page annotation: every detected
issue has the same quick action. The pending tool call returns the exact issue
and a fix suggestion. Only this confirmed response moves the item to *sent*.

The **Prompts** library stays copy-only because its entries are proactive ideas,
not detected issues with evidence to deliver through MCP.

**Round trip complete**

  The widget and agent exchanged a real issue. Copy prompt remains a separate
  clipboard fallback; it never claims that an agent received anything.

If the status does not match a step, use [Troubleshooting](/docs/troubleshooting).
For multiple dev servers, give each one a different `projectId` and keep using
the same hub. Requests to the configured hub URL and its API paths are excluded
from duplicate-request findings; other localhost requests are still monitored.