# 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.

```text
project A widget ─┐                    ┌─ bridge ─ agent A
project B widget ─┴─ shared hub :4200 ─┴─ bridge ─ agent B
```

Because 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

1. The agent calls `list_projects` and `watch_for_issue`.
2. The widget reports **Agent connected**.
3. The user clicks **Send to agent** on an issue.
4. The tool returns the issue and fix suggestion; the widget marks it sent.
5. The agent fixes the code and calls `resolve_issue`.
6. The agent watches again or calls `release_project`.

  - [Claude Code](/docs/ai-agents/claude-code.md): Register the connect bridge.
  - [Cursor](/docs/ai-agents/cursor.md): Configure the same bridge command.
  - [Tool reference](/docs/reference/mcp-tools.md): Parameters, responses, and HTTP routes.