Agent integration overview
How the shared hub, per-client MCP bridge, project routing, and exclusive watcher lease work.
VibeCheck uses two local process roles:
- one long-running hub receives browser snapshots and button dispatches for every local project; and
- each MCP client launches a stdio bridge that connects tools to that hub.
project A widget ─┐ ┌─ bridge ─ agent A
project B widget ─┴─ shared hub :4200 ─┴─ bridge ─ agent BBecause only the hub binds port 4200, opening another agent client does not cause the port collisions common to single-process browser/MCP integrations.
Routing and ownership
Snapshots, issue queues, histories, and leases are keyed by projectId. One
agent session can watch one project, and one project can have one healthy
watcher. A second watcher gets lease-conflict; it never steals the queue.
The lease is heartbeated every 5 seconds, reports stale after 10 seconds, and
expires after 15 seconds. Use release_project to move immediately.
The nine tools
| Tool | Purpose |
|---|---|
list_projects | Discover active project IDs and watcher state. |
get_performance_snapshot | Read one project's latest metrics. |
get_detected_issues | Read one project's active issues. |
get_fix_suggestions | Get a fix guide for one issue. |
watch_performance | Claim a project and wait for its next snapshot. |
watch_for_issue | Claim a project and wait for a widget dispatch. |
acknowledge_issue | Acknowledge an issue. |
resolve_issue | Resolve an issue. |
release_project | Release this session's lease. |
If exactly one project is active, project_id is optional. When several are
active, project-scoped tools fail with project-ambiguous until the agent passes
one explicitly.
Widget-driven loop
- The agent calls
list_projectsandwatch_for_issue. - The widget reports Agent connected.
- The user clicks Send to agent on an issue.
- The tool returns the issue and fix suggestion; the widget marks it sent.
- The agent fixes the code and calls
resolve_issue. - The agent watches again or calls
release_project.