vibecheck0.3.0
Concepts

Architecture

How core, react, mcp, and the protocol package fit into one pipeline.

VibeCheck is a short, one-directional pipeline. Metrics are measured in the browser, turned into issues, POSTed to a local server, and read back by your coding agent. Four packages divide that work along a single seam: the browser side and the agent side never share a runtime, only a wire contract.

VibeCheck package architectureThe protocol package is the shared contract feeding core and mcp. On the browser side, core is depended on by react which is used by your app. On the agent side, the standalone mcp package runs an HTTP receiver plus MCP tools and talks to the AI agent over stdio. The browser and agent sides connect only through a single POST to /api/snapshot.BROWSER SIDEAGENT SIDECONTRACTprotocolVibeSnapshot · VibeIssuetype-onlyzod schemaCOREcollectors + detectorszero runtime depsREACT<VibeCheck /> overlaypeer: React 18+YOUR APPmounts the widgetrenders your UIMCPHTTP receiver + toolslocalhost:4200 · stdioAI AGENTreads 9 MCP toolsover stdioPOST /api/snapshot
Four packages, one seam. core → react → your app on the browser side; mcp stands alone on the agent side. They share only the protocol contract and one HTTP POST — never a runtime import.

The pipeline

The VibeCheck round-trip pipelineBrowser collectors feed the VibeCheckEngine, which the beacon POSTs to the MCP server on localhost:4200; the AI agent reads the detected issues and proposes the fix.BROWSERCollectorssample the pageENGINEVibeCheckEnginesnapshot · 500msBEACONPOST /api/snapshotevery 2sMCP SERVERlocalhost:4200holds VibeStoreAI AGENTget_detected_issuesreads the evidenceFIXproposes the diffyou review & ship
The VibeCheck round-trip pipelineBrowser collectors feed the VibeCheckEngine, which the beacon POSTs to the MCP server on localhost:4200; the AI agent reads the detected issues and proposes the fix.BROWSERCollectorssample the pageENGINEVibeCheckEnginesnapshot · 500msBEACONPOST /api/snapshotevery 2sMCP SERVERlocalhost:4200holds VibeStoreAI AGENTget_detected_issuesreads the evidenceFIXproposes the diffyou review & ship
The loop that was missing from vibe coding: the browser measures, the beacon ships it, your agent reads the evidence — and proposes the fix.

The packages

PackageRoleRuntime deps
@wcgw/vibe-check-coreCollectors, detectors, VibeCheckEngine, BeaconClient.Zero.
@wcgw/vibe-checkReact overlay (<VibeCheck />, <PerfToggle />) + hooks.React 18+ (peer).
@wcgw/vibe-check-mcpShared HTTP hub + stdio bridge exposing nine project-scoped tools.@modelcontextprotocol/sdk, zod.
@wcgw/vibe-check-protocolSnapshots, issues, project envelopes, dispatch results, and lease states.Zero. Internal — bundled into the others.

The decoupling seam

The MCP package does not import core. The browser produces a VibeSnapshot, serializes it to JSON, and POSTs it; the server parses and validates it back into the same shape. Both sides depend on @wcgw/vibe-check-protocol for that type — core imports it type-only (preserving its zero-runtime-deps promise), while mcp also imports the DETECTOR_NAMES and SEVERITIES const arrays to build its zod validation schema. Deriving both from one source makes drift between browser and agent a compile error rather than a silent bug.

Why the split matters

You can run any layer on its own: core headless with no UI, the React widget with no MCP server, or the MCP server with any beacon pointed at it. Nothing above requires the layer below to be present.

What runs where

  • In the browser — collectors measure the page, detectors analyze each snapshot into issues, the engine orchestrates them, and the beacon (when a beaconUrl is configured) ships snapshots out.
  • On your machine — one hub holds isolated project stores, queues, and leases. Each agent client spawns a stdio bridge that talks to that hub. Only the hub binds the browser port.

Keep reading

Collectors

The six browser measurements and the Collector interface.

Detectors & audits

How snapshots become issues.

The Engine

Orchestration, config, and the scripted engine.

The Beacon

How snapshots reach the MCP server.

How it works

The packages that make up VibeCheck, and when you need each one.

Collectors

The six browser measurements VibeCheck records, and the Collector interface.

On this page

The pipelineThe packagesThe decoupling seamWhat runs whereKeep reading