Comet Browser (Comet-Bridge)

Comet-Bridge connects Equabot agents to Perplexity Comet for persistent browser automation. Unlike the equabot-managed browser, which runs ephemeral sessions, Comet-Bridge maintains a long-lived browser with authenticated sessions, tab group isolation, and multi-agent safety controls. Use Comet-Bridge when your agent needs:

Persistent login sessions (QBO, Mercury, Google, GitHub, etc.)
Multi-step workflows across page navigations
AI-powered web research via Perplexity search/research modes
Multi-agent tab isolation in shared browser sessions
Audit trails for browser actions

When to use which browser

Use equabot-managed browser when	Use Comet-Bridge when
Quick localhost checks and UI snapshots	Persistent authenticated sessions
One-off page validation	Multi-step automation and playbooks
Ephemeral, no login required	Need browser profile across many commands
Minimal setup	Multi-agent tab isolation needed

Both can coexist. The routing rule is: prefer the equabot-managed browser for fast, ephemeral checks; use Comet-Bridge for persistent sessions and multi-step workflows.

Prerequisites

Requirement	How to verify
Node.js 18+	`node --version`
Comet browser	Download from perplexity.ai/comet
Comet-Bridge repo	Clone the repo; set `COMET_BRIDGE_ROOT` if not in the workspace
npm install	Run `npm install` in the Comet-Bridge root

Quick start

# Start a Comet CDP session
comet session start

# Browse a page and capture content
comet browse https://example.com --content

# AI-powered search via Perplexity
comet search "latest AI frameworks 2026" --format json

# Take a screenshot
comet screenshot --full

# Run a multi-step workflow
comet auto --steps workflow.json

Architecture

Agent (Cursor/CLI)
  │
  ├── comet-mcp (MCP server) ──┐
  │                             ├── CDP ── Comet Browser (port 9222)
  └── comet CLI (cursor-comet.mjs) ──┘         │
                                          Tab Groups Extension
                                          (chrome.tabGroups API)

comet-mcp: MCP server that exposes 16 tools — 9 browsing (comet_connect, comet_ask, comet_poll, comet_stop, comet_screenshot, comet_mode, comet_shortcut, comet_read_page, comet_wait_for_idle), 1 tab management (comet_tab_groups), 4 lifecycle (comet_lifecycle_start, comet_lifecycle_complete, comet_lifecycle_abort, comet_lifecycle_update), and 2 task management (comet_task_status, comet_delegate).
comet CLI: Node wrapper (comet <command>) that routes to core scripts with startup gating and lifecycle metadata.
Tab Groups Extension: Chrome MV3 extension loaded in Comet that enables programmatic tab group management.

MCP-to-CLI fallback

When comet-mcp is unavailable (not built, not registered, or the MCP transport fails), agents safely degrade to the comet CLI wrapper. Both paths enforce identical safety controls: identity requirements, tab ownership, startup gating, and audit masking. The route field in lifecycle metadata indicates which path was used (mcp or cli), and fallbackUsed: true flags runs that degraded from MCP. Tab-group and multi-agent operations that require the extension bridge are hard-blocked in both channels when the extension is missing — fallback does not bypass safety gates.

MCP server setup (comet-mcp)

Published package — add to your Cursor MCP configuration (~/.cursor/mcp.json) or ~/.claude.json:

{
  "mcpServers": {
    "comet-bridge": {
      "command": "npx",
      "args": ["-y", "@shawnowen/comet-mcp"]
    }
  }
}

The repo-root .mcp.json is the canonical example. Local development — point to your local checkout with environment variables for the Comet binary and Command Center lifecycle endpoint:

{
  "mcpServers": {
    "comet-bridge": {
      "command": "node",
      "args": ["/path/to/Comet-Bridge/comet-mcp/dist/index.js"],
      "env": {
        "COMET_PATH": "/Applications/Comet.app/Contents/MacOS/Comet",
        "COMET_CC_LIFECYCLE_URL": "http://localhost:3001/command-center/api/comet/lifecycle"
      }
    }
  }
}

Variable	Purpose	Default
`COMET_PATH`	Absolute path to the Comet browser binary	Auto-detected from standard install locations
`COMET_CC_LIFECYCLE_URL`	Command Center lifecycle API endpoint for run tracking	`http://localhost:3001/command-center/api/comet/lifecycle`

MCP tools

Tool	Description
`comet_connect`	Connect to Comet browser (auto-starts CDP if needed)
`comet_ask`	Send a task to Perplexity AI and wait for response
`comet_poll`	Check progress on long-running tasks
`comet_stop`	Stop current Perplexity task
`comet_screenshot`	Capture current page
`comet_mode`	Switch Perplexity modes: search, research, labs, learn
`comet_shortcut`	Trigger a Comet Query Shortcut (reusable AI prompts with pre-configured modes)
`comet_read_page`	Extract page content as accessibility tree and/or clean text
`comet_wait_for_idle`	Wait for network activity to settle before proceeding
`comet_tab_groups`	Manage Chrome tab groups (requires extension). Actions: `list`, `list_tabs`, `create`, `update`, `move`, `ungroup`, `delete`, `save_group`, `restore_group`, `archive_group`, `list_archived`
`comet_lifecycle_start`	Register a new lifecycle run in Command Center
`comet_lifecycle_complete`	Mark a run as completed
`comet_lifecycle_abort`	Abort a run with optional reason
`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

CLI reference

The comet CLI is the unified wrapper for all Comet-Bridge commands.

comet <command> [args...]

Commands

Command	Purpose
`session`	Start, stop, check status of Comet CDP sessions
`browse`	Navigate to URL, capture content/links/title
`search`	Perplexity AI search (text, JSON, or markdown output)
`scrape`	Structured data extraction (tables, JSON-LD, CSS selectors)
`interact`	Click, fill, scroll, evaluate on pages
`screenshot`	Full page, viewport, selector, or clip screenshots
`pdf`	Generate PDF from current page
`network`	HAR capture, request interception, URL blocking, response mocking
`monitor`	Page change detection with diffs and notifications
`keepalive`	Prevent session timeouts for authenticated sites
`auto`	Multi-step workflow execution from JSON step files
`perf-audit`	Route regression testing and performance metrics extraction (Spec 050)
`bootstrap`	Run readiness checks (app, CDP, MCP, extension, config)
`readiness`	Generate readiness report (machine-readable + human-readable)

Lifecycle flags

Browser commands (browse, auto, interact, etc.) accept lifecycle flags for run tracking:

Flag	Purpose	Default
`--route <mcp\|cli\|http>`	Execution channel identifier	`cli`
`--run-id <uuid>`	Unique run identifier	Auto-generated UUID
`--agent-id <id>`	Agent identity for ownership	`COMET_AGENT_ID` env
`--task-thread <id>`	Task-thread scope	`COMET_TASK_GROUP` env

These flags propagate into the lifecycle envelope and audit artifacts.

Session management

comet session start          # Start Comet with CDP on default port
comet session start --port 9333  # Custom port
comet session status         # Check if running
comet session connect        # Verify CDP connectivity
comet session kill           # Stop the session

Configuration

Comet-Bridge uses scripts/comet-config.mjs for configuration, validated at load time.

Environment overrides

Variable	Purpose	Default
`COMET_BRIDGE_ROOT`	Comet-Bridge repo root directory	Parent of `scripts/`
`COMET_EXECUTABLE_PATH`	Comet browser binary path	`/Applications/Comet.app/Contents/MacOS/Comet`
`COMET_CDP_PORT`	CDP debug port	`9222`
`COMET_CDP_HOST`	CDP host	`127.0.0.1`
`COMET_OUTPUT_BASE`	Output root for screenshots, PDFs, etc.	`~/.claude/comet-browser/output`
`COMET_AGENT_ID`	Agent identity for tab ownership	(unset)
`COMET_TASK_GROUP`	Task group / task-thread scope	(unset)
`COMET_ISOLATE_GROUPS`	Override `isolateGroups` config (config default is `true`)	(unset; config default applies)
`COMET_RUN_ID`	Run identifier for lifecycle tracking	(auto-generated UUID)
`COMET_RUN_ROUTE`	Execution channel (`mcp`, `cli`, `http`)	`cli`
`COMET_MCP_FALLBACK`	Set by agent when MCP-to-CLI fallback occurs	(unset)
`COMET_RUN_STATUS`	Auto-propagated to child scripts by lifecycle engine	(auto; not user-set)
`COMET_AUDIT_SESSION_ID`	Auto-propagated audit session link for child scripts	(auto; not user-set)
`COMET_CC_LIFECYCLE_URL`	Command Center lifecycle endpoint URL	`http://localhost:3001/command-center/api/comet/lifecycle`

Output directories

All output follows a standard contract under COMET_OUTPUT_BASE:

~/.claude/comet-browser/output/
  ├── screenshots/
  ├── pdfs/
  ├── scraped/
  ├── har/
  ├── audit/
  ├── assistant/
  ├── research/
  └── labs/

Multi-agent safety

When multiple agents share the same Comet browser, Comet-Bridge enforces tab ownership and isolation to prevent cross-agent interference.

Tab ownership

Each tab is marked with an agent identity via a document title prefix: [comet-agent:<id>]. Agents can only perform sensitive actions (click, fill, navigate) on tabs they own.

Identity

Multi-agent mode requires identity via CLI flags or environment:

# Via CLI flags
comet auto --steps workflow.json --agent-id my-agent-1

# Via environment
COMET_AGENT_ID=my-agent-1 comet auto --steps workflow.json

# Task-thread scope
COMET_TASK_GROUP=svf-1099-filing comet auto --steps workflow.json

Tab group isolation

When isolateGroups is enabled (default), each agent/task gets its own Chrome tab group. The Comet Tab Groups Bridge extension is required for this feature.

Enforcement layers

Ownership is enforced at three tiers, each catching violations at a different level:

Tier	Guard	What it does
1 — Entry gate	`requireIdentityForMultiAgent()`	Blocks multi-agent runs that lack `agentId` or `taskThreadId` before any browser work starts.
2 — Page proxy	`createGuardedPage(page, identity)`	Wraps a Playwright `Page` in a `Proxy` that intercepts every method call. Sensitive methods are routed through ownership checks automatically.
3 — Action guard	`guardSensitiveAction(page, identity, action, fn)`	Per-action ownership verification. Checks the page title for the correct `[comet-agent:<id>]` prefix before executing the action.

In single-agent mode (no agentId/taskThreadId set), all three tiers are effectively no-ops and impose no overhead.

Sensitive actions

The following 17 Playwright Page methods are classified as sensitive and require ownership verification in multi-agent mode: goto, click, dblclick, fill, type, press, selectOption, setInputFiles, check, uncheck, hover, dragAndDrop, evaluate, setContent, reload, goBack, goForward Non-sensitive methods (e.g. title(), url(), screenshot(), content()) pass through without ownership checks.

Ownership errors

When an agent attempts a sensitive action on a tab it does not own, Comet-Bridge throws an OwnershipError:

Property	Value
`name`	`OwnershipError`
`code`	`OWNERSHIP_VIOLATION`
`agentId`	The agent that attempted the action
`taskThreadId`	The task thread scope of the caller
`pageUrl`	The URL of the tab (`sanitizeUrl` strips query params and hash fragments; invalid URLs preserved as-is)
`action`	The Playwright method that was blocked (e.g. `click`)

Consumers can catch this error by checking err.code === 'OWNERSHIP_VIOLATION' or err instanceof OwnershipError.

Startup gating

The comet CLI enforces safety checks before running commands. These gates prevent unsafe multi-agent operations.

Policy summary

Scenario	Behavior
Single-agent, any command	Always allowed
Diagnostic commands (`bootstrap`, `readiness`, `session`)	Always allowed
Multi-agent, no identity set	Blocked with remediation instructions
Multi-agent, CDP not running	Blocked with start instructions
Multi-agent + tab isolation, extension not loaded	Blocked with extension setup instructions
Multi-agent, no tab isolation	Warning issued, proceeds with title-prefix ownership

Bypass

Pass --skip-gate to bypass gating (not recommended for production):

comet auto --skip-gate --multi-agent --steps workflow.json

Opt out of tab isolation

Pass --no-isolate-groups to use title-prefix-only ownership (no extension required):

COMET_AGENT_ID=agent-1 comet auto --no-isolate-groups --steps workflow.json

Run lifecycle

Every browser run tracked by Comet-Bridge follows a lifecycle state machine. Both MCP and CLI paths emit identical lifecycle metadata using the shared lifecycle-metadata.mjs module.

States

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

Transitions

From	Allowed transitions
`pending`	`running` (start), `aborted` (cancel), `failed` (error before start)
`running`	`completed` (success), `aborted` (cancel), `failed` (error)
`completed`	None (terminal)
`aborted`	None (terminal)
`failed`	None (terminal)

Terminal states (completed, aborted, failed) allow no further transitions. Attempting an invalid transition throws a deterministic error.

Lifecycle envelope fields

Each run produces a lifecycle envelope with these fields:

Field	Type	Required	Description
`taskThreadId`	string	Yes	Task-thread identifier from the orchestration layer
`runId`	string	Yes	Unique run identifier (auto-generated UUID if omitted)
`status`	enum	Yes	Current lifecycle state
`startedAt`	ISO 8601	Yes	When the run was created
`route`	`mcp` \| `cli` \| `http`	No	Execution channel (`--route` flag or `COMET_RUN_ROUTE` env)
`fallbackUsed`	boolean	No	`true` when MCP-to-CLI fallback occurred (default `false`)
`agentId`	string	Multi-agent	Agent identity (`--agent-id` or `COMET_AGENT_ID`)
`tabGroupId`	string	No	Chrome tab group ID when tab isolation is active
`auditSessionId`	string	No	Links run to a browser-audit session artifact
`workflowId`	string	No	Workflow or playbook identifier
`completedAt`	ISO 8601	No	Set automatically on terminal transitions
`failureReason`	string	No	Human-readable reason on `aborted` or `failed`
`metadata`	`Record<string, unknown>`	No	Arbitrary key-value data attached via update operation

MCP/CLI parity

Both execution paths produce identical 13-field envelopes:

MCP path: comet-mcp tools use lifecycle-mcp-adapter.mjs which calls createLifecycleEnvelope({ route: 'mcp' }).
CLI path: cursor-comet.mjs calls createLifecycleEnvelope({ route: 'cli' }) for browser commands.

The shared lifecycle-metadata.mjs module ensures field names, types, and transition rules are the same regardless of invocation channel. When MCP is unavailable and the agent falls back to CLI, the envelope carries route: 'cli' and fallbackUsed: true.

Audit artifacts

Lifecycle events are persisted as JSON files under {COMET_OUTPUT_BASE}/audit/:

audit/
  ├── lifecycle-start-{runId}-{timestamp}.json
  ├── lifecycle-update-{runId}-{timestamp}.json
  ├── lifecycle-complete-{runId}-{timestamp}.json
  ├── lifecycle-abort-{runId}-{timestamp}.json
  └── lifecycle-fail-{runId}-{timestamp}.json

Each file contains the full lifecycle envelope plus the event type and timestamp. Audit sessions (browser-audit.mjs) also write lifecycle events to lifecycle.jsonl within the session directory.

Dual-Stream Audit Architecture

Comet-Bridge persists lifecycle events via two parallel audit streams that are always written together. They complement each other and serve different use cases.

Stream	Writer	Output Location	Granularity
Session-scoped	`browser-audit.mjs` (`BrowserAuditSession`)	`~/equabot/audit/browser-sessions/{sessionId}/lifecycle.jsonl` + `metadata.json`	Per-session directory; includes per-action files and screenshots
Run-oriented	`audit-logger.mjs` (`logLifecycleEvent()`)	`{COMET_OUTPUT_BASE}/audit/{runId}.jsonl`	Per-run JSONL; `lifecycle_*` events interleaved with `run_start`, `step`, `action`, `error`, `artifact`, and `run_end` events

The runId field is present in both streams and serves as the cross-correlation key. Given a runId, you can locate the corresponding session directory and run JSONL to reconstruct a complete audit picture of the run.

Bootstrap and readiness

Run readiness checks to verify all dependencies before using Comet-Bridge:

comet bootstrap          # Human-readable output
comet bootstrap --json   # Machine-readable JSON

Checks performed:

Comet app binary exists and is executable
CDP connection is reachable
comet-mcp server is built
Tab Groups Bridge extension is loaded
Configuration is valid
Output directories are writable

Exit codes

Code	Meaning
`0`	All checks pass
`1`	One or more critical checks failed
`2`	Warnings only (degraded mode viable)

Readiness tiers

The comet readiness command assesses readiness at two tiers:

Tier	Required checks	When to use
Pilot	Comet app, CDP, config validity, output dirs	Single-agent or early multi-agent adoption. MCP and extension may show warnings.
Broad	All 6 checks pass (app, CDP, MCP build, extension bridge, config, output)	Full multi-agent deployment with tab-group isolation and MCP tools.

comet readiness --json   # Includes "readiness.tier": "Pilot" or "Broad"

The tier assessment uses assessReadinessTier() internally: Pilot requires core + CDP + config + output; Broad additionally requires MCP build and extension bridge.

Telemetry

The readiness report includes an operational telemetry section aggregated by collectTelemetrySummary() from events persisted to {COMET_OUTPUT_BASE}/audit/telemetry-events.jsonl. Four event types are recorded:

Event type	What it tracks
`route`	Which execution channel (`mcp`, `cli`, `http`) handled each run
`fallback`	Runs that degraded from MCP to CLI (rate + count)
`ownership`	Multi-agent ownership check outcomes (violations, passes)
`completion`	Terminal state distribution (completed, aborted, failed) and average run duration

comet readiness                  # Includes telemetry by default
comet readiness --no-telemetry   # Skip telemetry aggregation
comet readiness --telemetry-days 7  # Adjust lookback window (default: 30)

Tab Groups Bridge extension

The extension enables programmatic tab group management via the Chrome tabGroups API (not available through CDP alone).

Setup

Open comet://extensions in Comet browser
Enable “Developer mode” (top-right toggle)
Click “Load unpacked” and select the comet-mcp/extension/ directory in the Comet-Bridge repo
Verify the “Comet Tab Groups Bridge” extension appears with an active service worker

Tab group operations

Available via comet_tab_groups MCP tool or programmatically:

Action	Description
`list`	List all tab groups
`list_tabs`	List tabs in a specific group
`create`	Create a new tab group
`update`	Rename, recolor, or collapse a group
`move`	Move tabs between groups
`ungroup`	Remove tabs from a group
`delete`	Close all tabs in a group
`save_group`	Persist tab group state to the ETT archive (keyed by `taskThreadId`)
`restore_group`	Restore an archived tab group and reopen its tabs
`archive_group`	Collapse and archive a tab group for later restoration

Group colors: grey, blue, red, yellow, green, pink, purple, cyan, orange.

Cookbook

Authenticated session keepalive

# Keep a QBO session alive for 60 minutes, refreshing every 5 minutes
comet keepalive --url "https://qbo.intuit.com" --interval 300 --duration 60

Structured data extraction

# Extract tables from a page
comet scrape "https://example.com/data" --table -o data.json

# Extract content by CSS selector
comet scrape "https://example.com" -s "main article" --output content.json

Multi-step workflow

# Run a JSON step file
comet auto --steps workflow.json --agent-id agent-1

Lifecycle-tracked workflow

# Run with explicit route and run-id (e.g. from MCP fallback path)
comet auto --steps workflow.json --route cli --run-id abc-123 --agent-id bot-1

Lifecycle flags attach run metadata to the output JSON and audit artifacts. See Run lifecycle for details.

Multi-viewport visual QA

# Capture screenshots in 4 viewports (desktop, laptop, tablet, mobile)
comet screenshot "https://localhost:3000" --multi --full

Perplexity research workflow

Use the MCP tools to run a deep research query and extract results:

comet_connect — attach to browser
comet_mode with mode research — switch to research mode
comet_ask with your research query — send the prompt
comet_read_page — extract the full response

Network capture

# Record HAR for all requests
comet network "https://example.com" --har --output traffic.har

Relationship to equabot browser

Comet-Bridge and the equabot-managed browser are complementary:

The equabot browser is built into the Gateway, uses Playwright, and is controlled via the browser agent tool. It launches isolated Chromium profiles for each run.
Comet-Bridge is an external connection to the Perplexity Comet browser. It maintains persistent sessions with authenticated sites and provides AI-powered search via Perplexity.

They share no state, use different CDP ports (equabot: 18800+, Comet: 9222), and can run simultaneously.

Troubleshooting

CDP not reachable

# Check if Comet is running with CDP
comet session status

# Start Comet with CDP
comet session start

# Verify CDP manually
curl http://127.0.0.1:9222/json/version

Extension not detected

# Run bootstrap to check extension status
comet bootstrap

# If extension-bridge shows WARN, reload the extension in comet://extensions

Multi-agent command blocked

If you see [comet-gating] BLOCKED, check the error message for the specific issue:

Missing identity: set COMET_AGENT_ID or COMET_TASK_GROUP
CDP unreachable: start Comet with comet session start
Extension missing: load the Tab Groups Bridge extension

Security

Comet-Bridge controls a real browser with real sessions. Treat CDP access as sensitive.
Keep CDP bound to loopback (127.0.0.1). Never expose port 9222 to the network.
Tab ownership prevents cross-agent interference but is not a security boundary; it is a safety mechanism for shared sessions.

Audit masking

Sensitive fields in audit logs and lifecycle events are masked automatically before persistence. Masking operates in four layers:

Layer	Source (`browser-audit.mjs`)	Count	What it matches	Examples
Field-name patterns	`SENSITIVE_PATTERNS`	20	Regex patterns matched against JSON field names	`password`, `secret`, `token`, `apiKey`, `apikey`, `creditCard`, `cardNumber`, `cvv`, `ssn`, `socialSecurity`, `authorization`, `bearer`, `set-cookie`, `sessionCookie`, `jwt`, `privateKey`, `signingKey`, `otp`, `totp`, `mfaCode`
Partial masking	`PARTIAL_MASK_PATTERNS`	3	Account, routing, and bank number fields — last 4 digits shown, middle digits replaced with `*`	`accountNumber`, `routingNumber`, `bankAccountNumber`
CDP URL masking	`CDP_URL_FIELD_PATTERNS`	4	CDP/WebSocket URL fields where session tokens may appear in the path	`cdpUrl`, `wsEndpoint`, `debuggerUrl`, `websocketUrl` — path and query are redacted, host:port preserved
Value heuristics	Content-based	4	Secrets in non-standard fields detected by value shape	JWT tokens (`eyJ...`), `Bearer` prefixes, hex strings 40+ chars, base64 blobs 40+ chars

Additionally, startRun() in audit-logger.mjs filters argv arrays for 8 CLI flag-name patterns (--password, --token, --secret, --key, --credential, --auth, --api-key, --private-key), replacing the following value with [REDACTED]. Masking covers audit action logs, lifecycle event payloads, and metadata envelopes. Step data and results in verbose output are masked via maskSensitiveData(). Conversation logs apply the same masking before persistence. OwnershipError sanitizes pageUrl by stripping query parameters and hash fragments before storing, preventing accidental credential exposure in error messages.

​Comet Browser (Comet-Bridge)

​When to use which browser

​Prerequisites

​Quick start

​Architecture

​MCP-to-CLI fallback

​MCP server setup (comet-mcp)

​MCP tools

​CLI reference

​Commands

​Lifecycle flags

​Session management

​Configuration

​Environment overrides

​Output directories

​Multi-agent safety

​Tab ownership

​Identity

​Tab group isolation

​Enforcement layers

​Sensitive actions

​Ownership errors

​Startup gating

​Policy summary

​Bypass

​Opt out of tab isolation

​Run lifecycle

​States

​Transitions

​Lifecycle envelope fields

​MCP/CLI parity

​Audit artifacts

​Dual-Stream Audit Architecture

​Bootstrap and readiness

​Exit codes

​Readiness tiers

​Telemetry

​Tab Groups Bridge extension

​Setup

​Tab group operations

​Cookbook

​Authenticated session keepalive

​Structured data extraction

​Multi-step workflow

​Lifecycle-tracked workflow

​Multi-viewport visual QA

​Perplexity research workflow

​Network capture

​Relationship to equabot browser

​Troubleshooting

​CDP not reachable

​Extension not detected

​Multi-agent command blocked

​Security

​Audit masking