Agent Recording

Overview

Agent Recording makes VibeCheck agent-friendly. You give your AI coding assistant a task in plain English — "go to this page, click this and that, and check the result" — and the VibeCheck MCP server opens a real browser on your machine. The agent performs the steps while VibeCheck records the entire session. When it finishes, you get a normal VibeCheck track link you can share with anyone:

• Video of everything the agent did — with a visible cursor, click ripples, and captions describing each action, so anyone can follow along
• Console logs, including JS errors
• Network requests, with response bodies for API calls
• A labeled action timeline ("Clicked: Login button") synced to the video

Videos stay short, too: with ffmpeg installed, the idle "thinking time" between agent actions is cut out automatically before upload — a 5-minute session typically becomes under a minute, with the timeline still perfectly synced.

No AI runs inside VibeCheck — your assistant does the thinking and clicking, VibeCheck is the recorded browser. You pay nothing extra beyond your existing AI tool.

How it works

You: "Go to staging.myapp.com/cart and validate the total is $42.
      Record it and give me the link."
        │
        ▼
Claude Code / Cursor ──▶ opens a local browser window (visible)
        │                 • navigates, clicks, types — every step recorded
        ▼
browser_finish ──▶ uploads to VibeCheck ──▶ shareable link:
                   https://app.vibecheck-qa.com/tracks/1783...

Because the browser runs locally, the agent can test anything you can reach — including localhost dev servers and staging environments behind a VPN.

Installation

Setup takes about a minute: generate an API key, then connect the MCP server to your AI tool. That's it.

Before you start, make sure you have:

• Node.js 18+ installed — check with node --version (get it at nodejs.org if not)
• One of: Claude Code, Claude Desktop, Cursor, Windsurf, or VS Code with Copilot

No browser install needed. The agent automatically uses your existing Google Chrome or Microsoft Edge (with a fresh, isolated profile — your bookmarks, logins, and cookies are never touched). If neither is installed, a browser is downloaded automatically on first run. To pre-download it instead, run npx playwright install chromium.

Step 1 — Get your API key

Recordings are uploaded to your VibeCheck account, so the server needs a key to prove it's you:

1. Sign in at app.vibecheck-qa.com
2. Open the API Keys page (in the sidebar, or directly at app.vibecheck-qa.com/api-keys)
3. Click Generate key

⚠️ The key is shown only once — if you lose it, just revoke it and generate a new one. You can have up to 5 active keys (e.g. one per machine).

Step 2 — Connect it to your AI tool

The fast way: the key-created dialog gives you ready-made setup — a copy-paste command for Claude Code with your key already inside, and one-click Add to Cursor / Add to VS Code buttons. Use those and skip straight to Step 3.

Setting it up manually instead? Pick your tool below and replace vck_your_key_here with the key from Step 1.

Claude Code

Run this in a terminal (anywhere):

claude mcp add vibecheck \
  -e VIBECHECK_API_KEY=vck_your_key_here \
  -- npx -y @vibecheck-mcp/mcp

Claude Desktop

Add this to your config file — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json — then restart Claude Desktop:

{
  "mcpServers": {
    "vibecheck": {
      "command": "npx",
      "args": ["-y", "@vibecheck-mcp/mcp"],
      "env": {
        "VIBECHECK_API_KEY": "vck_your_key_here"
      }
    }
  }
}

Cursor

Add the same JSON block to .cursor/mcp.json in your project (or Cursor Settings → MCP → Add new server).

Windsurf

Add the same JSON block to ~/.codeium/windsurf/mcp_config.json.

VS Code

Add to .vscode/mcp.json in your project (note the key is servers, not mcpServers):

{
  "servers": {
    "vibecheck": {
      "command": "npx",
      "args": ["-y", "@vibecheck-mcp/mcp"],
      "env": {
        "VIBECHECK_API_KEY": "vck_your_key_here"
      }
    }
  }
}

Step 3 — Verify it works

Open a new session in your AI tool (MCP servers load at session start) and paste:

Go to https://example.com, then finish the recording titled
"Setup test" and give me the link.

You should see a browser window flash open, and within ~15 seconds the agent replies with a .../tracks/... link. Open it — if the video plays, you're done. 🎉

If something fails:

If you only want to analyze existing tracks (the read-only MCP tools), you can skip Step 1 entirely — no API key needed.

Usage

Start a session in your AI tool and describe the task naturally. End with "finish the recording and give me the link" so the agent knows to upload:

Go to https://staging.myapp.com/pricing, verify the Pro plan
shows $29/month, then finish the recording and give me the link.

The agent opens a browser window (you can watch it work), performs the steps, and replies with something like:

Recording uploaded to VibeCheck.
Shareable link: https://app.vibecheck-qa.com/tracks/1783009013047-dc126eed
Duration: 12s · console errors: 0 · network errors: 0 · actions: 5

Open the link to watch the video with synced Console, Network, and Actions tabs — and share it with anyone, no account needed.

Example tasks

Validate something on a page

Open localhost:3000/checkout, add the first product to the cart,
and confirm the total updates. Record it and send me the link.

Reproduce a bug from an existing report

Here's a bug report: https://app.vibecheck-qa.com/tracks/abc123
Analyze it, then try to reproduce the same steps on localhost:3000
and record your attempt.

Prove a fix works

You just fixed the login redirect bug — now prove it. Go through
the login flow on localhost:3000 and attach the recording link
to the PR description.

Smoke-test after a deploy

We just deployed. Go through sign-in → dashboard → create project
on production and record it. Flag any console errors you see.

Throw a recording away

Actually, discard that recording — don't upload it.

The recording tools

Your AI assistant uses these automatically — you don't call them yourself:

Good to know

• Plan limits: agent recordings count toward your plan's monthly recordings (Free: 25/month), and the limit is checked before the browser opens.
• Safe by default: the browser is a fresh, isolated profile — no cookies or logins from your daily browser. Nothing is uploaded until the agent calls browser_finish (and discard throws it away).
• Failed upload ≠ lost recording: if the upload fails, the video is kept locally and the agent tells you the file path.
• Sharing model: track links are public-by-URL (unguessable ID) — the same as extension-recorded tracks. Don't record pages showing secrets you wouldn't put in a bug report.
• Watchable videos: the recording shows a cursor moving to every element the agent touches, a ripple on each click, and a caption naming the action — the overlay never interferes with the page and is hidden from the agent's own screenshots.
• Short videos: if ffmpeg is installed (brew install ffmpeg / apt install ffmpeg), idle time between actions is trimmed automatically and all timestamps are re-synced. Without ffmpeg the full video is uploaded. Set VIBECHECK_NO_CONDENSE=1 to always keep the full video.
• Headless mode: set VIBECHECK_HEADLESS=1 in the server's env to hide the browser window (useful in CI).

Requirements

• Node.js 18 or later
• Google Chrome or Microsoft Edge (auto-detected; a browser is auto-downloaded if neither exists)
• A VibeCheck account with a personal API key
• An AI tool that supports MCP (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code)
• Optional: ffmpeg, for automatic video condensing — everything works without it, videos are just longer