Quickstart

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:

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:

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.

pnpm add -D @wcgw/vibe-check

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:

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:

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

Other clients use the same spawned command:

{
  "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:

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.

If the status does not match a step, use 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.