Comet-Bridge (Cursor browser automation)

Comet-Bridge is a CDP-based browser automation orchestrator used by Cursor agents for persistent, authenticated browser sessions. It connects to the Perplexity Comet browser via Chrome DevTools Protocol and provides multi-step workflow execution, tab-group management, and identity-aware ownership enforcement. Comet-Bridge is distinct from the Equabot-managed browser. Use Comet-Bridge for persistent authenticated sessions (QBO, Mercury, Google) and multi-step playbooks. Use the Equabot browser for quick in-IDE checks and ephemeral validation.

Architecture

Cursor Agent
   │
   ├─ MCP tools (comet_connect, comet_ask, comet_lifecycle_*)
   │     └─ comet-mcp stdio server ──► Comet Browser (CDP)
   │                                      └─ Tab Groups Extension
   │
   ├─ CLI fallback (comet auto/browse/scrape/...)
   │     └─ cursor-comet.mjs ──► Comet scripts ──► Comet Browser
   │
   └─ Lifecycle sync ──► Command Center /command-center/api/comet/lifecycle
                               └─ taskThreads.ts lifecycle adapter
                                    └─ src/data/comet-runs/*.json

Channel routing

The browser-automation-routing rule selects the channel by intent:

Use case	Channel	Why
Quick localhost checks, UI snapshots	`cursor-ide-browser` MCP	Fast, ephemeral, no setup
Persistent sessions, multi-step automation	Comet-Bridge (MCP or CLI)	CDP profile, keepalive, ownership

When Comet MCP is unavailable, agents fall back to the comet CLI wrapper. The safety protocol (identity, ownership) is enforced on both paths.

Run lifecycle

Every Comet browser run has a lifecycle tracked by the Command Center lifecycle store.

States

State	Description
`pending`	Run created, not yet started (queued or deferred)
`running`	Run in progress; browser session active
`completed`	Run finished successfully
`aborted`	Run intentionally stopped (user cancel, timeout)
`failed`	Run ended with error (script failure, CDP disconnect)

Transition table

From / To	pending	running	completed	aborted	failed
pending	—	start	—	abort	fail
running	—	—	complete	abort	fail
completed	—	—	—	—	—
aborted	—	—	—	—	—
failed	—	—	—	—	—

completed, aborted, and failed are terminal (no further transitions). Operations are idempotent from terminal states.

Operations

Operation	Meaning
start	Create/register run; transitions to `running` (or `pending` if deferred)
update	Update run metadata while `running` (auditSessionId, tabGroupId, workflowId)
complete	Mark run as successfully finished
abort	Mark run as intentionally stopped
fail	Mark run as failed with a reason

Identity fields

Field	Required	Meaning
`runId`	Yes	Unique identifier for this browser run
`taskThreadId`	Yes	Links run to a task thread in Command Center
`agentId`	Multi-agent only	Agent identity for tab ownership and isolation
`route`	No	Channel used: `mcp`, `cli`, or `http`
`fallbackUsed`	No	`true` if execution used a fallback path

In multi-agent mode, both taskThreadId and agentId are required. Single-agent runs may omit agentId.

Graceful degradation

Lifecycle sync to Command Center is best-effort on both execution paths:

Path	Timeout	Source
CLI (`auto.mjs` → `lifecycle-sync.mjs`)	2 s	`AbortSignal.timeout(2000)`
MCP (`comet-mcp/src/index.ts`)	5 s	`AbortSignal.timeout(5000)`

On failure (timeout or non-2xx response), the sync function logs a [lifecycle-sync] warning and returns null. The run itself continues uninterrupted. A local JSON backup (auto-{timestamp}.json) is always written regardless of whether the sync succeeds, so run data is never lost. The endpoint URL can be overridden via the COMET_CC_LIFECYCLE_URL environment variable.

MCP tools

Comet-Bridge exposes tools via its MCP server (comet-mcp):

Tool	Purpose
`comet_connect`	Connect to Comet browser (auto-starts if needed)
`comet_ask`	Send prompt to Perplexity and wait for response
`comet_poll`	Check status of long-running tasks
`comet_stop`	Stop current task
`comet_screenshot`	Capture current page
`comet_mode`	Switch Perplexity mode (search/research/labs/learn)
`comet_shortcut`	Trigger a Comet Query Shortcut (reusable AI prompts)
`comet_read_page`	Extract page content as accessibility tree / clean text
`comet_wait_for_idle`	Wait for network activity to settle
`comet_tab_groups`	Manage Chrome tab groups (requires extension)
`comet_lifecycle_start`	Register a new lifecycle run
`comet_lifecycle_complete`	Mark a run as completed
`comet_lifecycle_abort`	Abort a run
`comet_lifecycle_update`	Update metadata on a running run (auditSessionId, tabGroupId, workflowId)
`comet_task_status`	Check task thread status from the orchestration layer
`comet_delegate`	Delegate a task to a sub-agent with lifecycle tracking

Tab ownership

In multi-agent mode, tabs are owned by a single identity (agentId or taskThreadId). Ownership is marked via the document title prefix [comet-agent:<id>] and enforced at three tiers:

Entry gate — identity required before browser work begins
Page-level — tab assigned to the requesting identity
Action-level — every sensitive action (click, fill, navigate) verifies ownership

Cross-identity access is blocked with a deterministic OwnershipError.

Install & Updates

Gateway Operations

Web Interfaces

Platforms

macOS Companion App

Comet bridge

Comet-Bridge (Cursor browser automation)

Architecture

Channel routing

Run lifecycle

States

Transition table

Operations

Identity fields

Graceful degradation

MCP tools

Tab ownership

See also

​Comet-Bridge (Cursor browser automation)

​Architecture

​Channel routing

​Run lifecycle

​States

​Transition table

​Operations

​Identity fields

​Graceful degradation

​MCP tools

​Tab ownership

​See also

Comet-Bridge (Cursor browser automation)

Architecture

Channel routing

Run lifecycle

States

Transition table

Operations

Identity fields

Graceful degradation

MCP tools

Tab ownership

See also