SSOT: OpenChrome as a host-neutral MCP browser harness

[shaun0927]

Purpose

This issue is the product-direction SSOT for OpenChrome.

OpenChrome should remain a host-neutral MCP browser harness for real Chrome: useful from Codex, Claude Code, Hermes Agent, OpenClaw, IDEs, CI jobs, dashboards, and custom MCP clients through the same MCP contract.

The goal is not to make OpenChrome a standalone agent, a hosted browser cloud, or a Playwright/Puppeteer replacement for deterministic scripts. The goal is to give any MCP-capable host agent a portable way to use real Chrome with reliable tools, structured facts, contract-verifiable evidence, portable memory, and safe isolation.

One-line identity

OpenChrome is a host-neutral MCP browser harness for real Chrome.

It gives any MCP-capable host agent authenticated browser continuity, structured browser facts, contract-verifiable evidence, portable memory, and safe isolation — without becoming the agent.

Non-identity

OpenChrome is not:

• a standalone scraping framework;
• a general Playwright/Puppeteer replacement for deterministic scripts;
• a server-side LLM agent;
• a Claude-only, Codex-only, Hermes-only, or OpenClaw-only plugin;
• an autonomous planning/runtime framework;
• a hosted browser cloud service;
• a place for hidden host-specific behavior that bypasses the MCP contract.

If a user wants a deterministic browser script without a host LLM or MCP client, Playwright or Puppeteer is usually the right tool. OpenChrome is for host agents that need a browser harness.

Primary product boundary

The MCP protocol is the product boundary.

A feature belongs in OpenChrome only if it can be exposed through portable MCP surfaces, such as:

• tools;
• resources;
• notifications and progress;
• transport behavior;
• client capability negotiation;
• portable local artifacts such as traces, evidence bundles, skill memory, and replay material.

Host-specific setup or UX integrations are allowed, but they must not define core behavior. A feature that only works because one specific host agent has custom behavior is integration sugar, not core product direction.

Host classes OpenChrome must serve

1. stdio single-client hosts

Examples:

• Claude Code;
• Codex CLI;
• Cursor;
• Windsurf;
• OpenCode-style clients;
• any stdio-native MCP client.

Requirements:

• stable stdio behavior;
• clear tool schemas;
• useful baseline tools/list;
• no hidden daemon dependency;
• clean lifecycle with the launching MCP client unless configured otherwise;
• robust error messages and tool responses that host LLMs can act on.

2. HTTP daemon and multi-client hosts

Examples:

• OpenClaw;
• dashboards;
• CI jobs;
• shared local operators;
• multi-agent systems;
• long-running local or remote MCP callers.

Requirements:

• Streamable HTTP transport;
• bearer-token or tenant-aware authentication;
• independent client lifecycles;
• session, tab, worker, and lane isolation;
• health and metrics endpoints;
• idle timeout;
• safe concurrent requests;
• no cross-client tab/reference contamination.

3. Agentic host runtimes

Examples:

• Hermes Agent;
• custom planners;
• browser-task frameworks;
• host-side LLM orchestration systems.

Requirements:

• facts and evidence, not hidden server-side judgment;
• contract-verifiable task completion;
• portable skill and memory recall;
• task/lane-scoped state;
• failure evidence;
• no OpenChrome-owned LLM planning loop.

4. Unknown MCP clients

Requirements:

• useful baseline behavior without client-specific assumptions;
• deterministic fallback when optional capabilities are absent;
• no mandatory dependency on sampling, elicitation, roots, tools/list_changed, or any other optional client capability;
• standards-first result shapes.

Product principles

P1. Host-neutral MCP first

Every core feature should work through standard MCP semantics before it is optimized for one host.

If a feature requires a specific host agent, it should be treated as integration sugar, not product identity.

P2. Harness, not agent

OpenChrome accepts tool calls, controls Chrome, returns facts, records evidence, and exposes memory.

The host agent decides what to do next.

OpenChrome must not call external LLM APIs directly. Server-side LLM planning, judging, merging, or autonomous task decomposition is out of scope for this repository.

P3. Real Chrome first

OpenChrome's durable advantage is real Chrome:

• real user profiles;
• real authenticated sessions;
• real tabs;
• real browser state;
• real network and UI behavior.

Therefore browser-visible polish is core product quality:

• no surprise blank tabs;
• no focus stealing;
• attach-mode user-tab protection;
• deterministic tab/session lifecycle;
• safe profile and context handling;
• clean shutdown and orphan prevention.

P3a. Shared Chrome requires a single CDP owner

OpenChrome may support many host sessions, workers, lanes, tabs, browser contexts, and even multiple MCP clients over one authenticated Chrome profile, but only one OpenChrome control plane should own the direct CDP connection and Chrome lifecycle for a given (port, userDataDir) pair.

The intended direction is not “one browser per task” and not “serialize all browser work.” The intended direction is:

• one Chrome/profile can be shared for memory and authenticated continuity;
• one OpenChrome broker/daemon owns Chrome lifecycle, CDP connection health, target ownership, cleanup, and reconnect;
• many MCP sessions/clients can submit work to that broker;
• different tabs, workers, contexts, or browser instances may run concurrently;
• commands targeting the same tab must be ordered through a per-target queue;
• destructive browser-wide operations such as target close, session cleanup, reconnect, browser restart, and memory-pressure cleanup must be centrally coordinated.

Unsafe shape:

Claude openchrome-mcp ┐
Codex openchrome-mcp  ├─> same Chrome :9222 / same userDataDir
OMX openchrome-mcp    ┘

Safe shapes:

MCP clients ─> one OpenChrome broker ─> same Chrome/profile ─> tab leases

or, when independent MCP processes are required:

Claude openchrome-mcp ─> Chrome :9222 / profile-claude
Codex openchrome-mcp  ─> Chrome :9223 / profile-codex
OMX openchrome-mcp    ─> Chrome :9224 / profile-omx

This principle is part of the real-Chrome product identity: profile sharing is valuable, but uncoordinated multi-controller CDP access is not a supported core architecture.

P4. Facts before decisions

OpenChrome captures, computes, stores, retrieves, normalizes, and verifies browser facts.

Judgment belongs to the host agent.

MCP sampling, elicitation, or other client-mediated mechanisms may improve a tool call when the connected client advertises support, but OpenChrome must keep a safe deterministic fallback.

P5. Evidence before claims

Public claims about speed, token efficiency, reliability, auth usability, developer experience, or agent task success must be benchmark-backed.

Mock-only, scaffold-only, partial, or operator-unverified results must not become headline claims.

Retired claims must not reappear unless replaced by measured, reproducible evidence.

P6. Verified memory only

Skill and selector memory should come from contract-verified successes and structured failed-run evidence.

Memory should guide host agents through MCP-visible context. It must not silently execute unverified actions or become hidden host-specific behavior.

P7. Core boring, pilot experimental

Core must remain stable, deterministic, portable, and backward-compatible.

Pilot may contain opt-in harness intelligence such as curator, recovery runtime, auto-memory, voting interfaces, and extension experiments, but pilot must still preserve the anywhere-compatible MCP constraint:

• no outbound LLM API calls from the server;
• no mandatory third-party credentials at boot;
• no platform-specific install requirement;
• no behavior change when pilot is off.

Strategic pillars

Pillar A — MCP portability layer

OpenChrome should first be an excellent portable MCP server.

Focus areas:

• stdio / HTTP / both transport compatibility;
• client capability negotiation;
• fallback for unknown clients;
• tool schema compatibility;
• tool annotations such as read-only, destructive, idempotent, and open-world behavior;
• progress and error semantics;
• portable context export/import;
• setup support for multiple clients;
• stable resources and result shapes.

Pillar B — Real Chrome lifecycle and isolation

OpenChrome should make real Chrome safe for host-agent work.

Focus areas:

• targetId-safe tab model;
• startup tab handling;
• attach vs isolated mode safety;
• profile/auth reuse;
• named contexts;
• task/session/worker/lane isolation;
• multi-client concurrency;
• no orphan Chrome processes;
• no surprise windows or tabs;
• deterministic cleanup.

Pillar B concurrency decision

The long-term concurrency model is single owner, many leases:

• Single CDP owner per (port, userDataDir): exactly one OpenChrome process owns direct Chrome lifecycle and CDP write access for a shared Chrome/profile.
• Many sessions over one owner: stdio, HTTP, and future client adapters can multiplex into the owner instead of spawning independent controllers.
• Tab leases: every managed target is leased to a session/client/worker/lane with owner metadata, expiry, and cleanup policy.
• Per-target queues: commands against the same tab are ordered; commands against different tabs can run concurrently.
• Central cleanup: target limits, memory pressure, TTL cleanup, oc_stop, reconnect, and browser restart must consult the shared registry before closing anything.
• Explicit isolation escape hatch: when a client needs independent lifecycle or trust boundary, it should use a separate port/profile instead of joining the shared owner.

This keeps the memory/auth benefits of a shared Chrome profile without allowing multiple MCP servers to race over target lifecycle.

Pillar C — Contract-verifiable browser work

OpenChrome should make browser task success auditable rather than vibe-based.

Focus areas:

• outcome contracts;
• oc_assert;
• oc_evidence_bundle;
• traces;
• replay artifacts;
• DOM, screenshot, network, console, and performance evidence;
• irreversible-action guardrails;
• postcondition-based task success;
• failure evidence that a host agent can use to recover.

Pillar D — Portable verified memory

OpenChrome should learn browser affordances without becoming an opaque agent.

Focus areas:

• state graph;
• domain-scoped skill memory;
• contract-success extraction;
• failed-run stats;
• deterministic skill artifacts;
• selector confidence;
• auto-recall as host-agent context;
• explicit provenance for every promoted skill or memory record.

Memory must be portable evidence exposed through MCP, not hidden behavior tied to one host agent.

Pillar E — Benchmark-backed positioning

OpenChrome should make competitive claims only through reproducible measurement.

Focus areas:

• local open-source competitor scope;
• exact version pins;
• environment metadata;
• live/measured vs mock/scaffold distinction;
• token efficiency;
• agent task success;
• speed and throughput;
• reliability and fault recovery;
• auth and real-world usability;
• developer experience;
• losing scenarios included in reports.

Pillar F — Optional expansion surfaces

OpenChrome may expand beyond CDP and baseline MCP only when the expansion is explicit, optional, and fallback-safe.

Examples:

• companion Chrome extension only for capabilities CDP cannot provide safely, such as first-party chrome.* APIs;
• MCP sampling for host-mediated ambiguity resolution;
• elicitation for user confirmation where supported;
• codegen and replay for auditability and portability.

These features should remain opt-in or enhancement-only until their portability and safety are proven.

Decision rules for future issues and PRs

Every substantive issue or PR should be able to answer:

1. Which strategic pillar does this advance?
2. Does it work for stdio and HTTP hosts, or is the limitation explicit?
3. What happens for unknown MCP clients?
4. Does it require optional client capabilities? If yes, what is the fallback?
5. Does it preserve core behavior when pilot is off?
6. Does it keep LLM judgment in the host?
7. Does it produce facts, evidence, memory, or artifacts in a portable form?
8. Does it affect real Chrome visible state? If yes, how are tab/session/profile safety preserved?
9. If it supports a public claim, where is the benchmark evidence?
10. Does it introduce any host-specific behavior that should instead be expressed through MCP?

Explicit non-goals

• server-side LLM planning;
• OpenChrome-owned autonomous agent loops;
• hidden host-specific behavior;
• unverified memory auto-execution;
• benchmark claims from mock-only data;
• replacing Playwright/Puppeteer for standalone deterministic scripts;
• requiring Chrome extension installation for core behavior;
• requiring third-party credentials at boot;
• making Claude Code, Codex, Hermes Agent, or OpenClaw the privileged product center.

Current evidence anchors

• Portability contract: docs/roadmap/portability-harness-contract.md
• Architecture: docs/architecture.md
• Transport lifecycle: docs/transport-lifecycle.md
• HTTP daemon: docs/getting-started/http-daemon.md
• Tool annotations: docs/mcp/tool-annotations.md
• v1.11 core/pilot split: README.md
• Benchmark status: benchmark/EPIC-1254-STATUS.md
• Competitor pins: benchmark/COMPETITORS.md
• Sampling PoC: feat(tools): sampling-driven disambiguation PoC for act (mcp-servers adoption 7) #876
• Companion extension RFC: rfc(pilot): optional companion Chrome extension for chrome.* APIs (history/bookmarks/downloads) — pilot-only opt-in (mcp-chrome adoption B1) #900
• Task-scoped lanes: feat(harness): task-scoped browser lanes for isolated parallel work #1037
• Recent pilot memory stack: feat(pilot/state-graph): minimal v1 node-hash anchor on TransactionRecord #1348, feat(pilot): auto-extract skills from contract successes + wire curator runner #1353, feat(pilot/state-graph): v2 hash folds DOM skeleton, v1 stays byte-stable #1354, feat(pilot/curator): sidecar-backed stats resolver + ok=false logging #1355, feat(pilot): auto-recall promoted curator skills on oc_task_run_start #1356, feat(pilot/curator): deterministic SKILL.md body builder from journal slice #1357, feat(pilot): auto-memory accretes per-selector confidence from contracts #1358
• Browser lifecycle polish: Fix extra blank startup NTP tab left after tabs_create #1346, fix(cdp): reuse startup NTP tab on first createPage to prevent extra blank tab #1347

Implementation backlog: stable shared-profile parallelism

The following work is needed to make “many sessions, shared Chrome profile, stable parallel tabs” a first-class OpenChrome capability.

1. Duplicate-controller detection and fail-fast guard

Goal: prevent accidental multiple openchrome-mcp controllers from attaching to the same (port, userDataDir).

Tasks:

• Add a process lock keyed by normalized port + userDataDir.
• Store lock metadata: PID, command, version, cwd, port, userDataDir, startedAt, lifecycle mode, and transport.
• On openchrome serve --auto-launch, refuse to start if a live owner already exists for the same key.
• Provide actionable error output: existing owner PID, client config likely responsible, and suggested alternatives.
• Allow explicit override only through a clearly named unsafe/debug flag, not by default.
• Treat stale locks as recoverable after PID liveness and Chrome endpoint validation.

Acceptance criteria:

• Starting two stdio MCP servers against the same port/profile fails before both attach to Chrome.
• Existing valid owner is not killed by a second startup attempt.
• Stale lock recovery is covered by tests.

2. Broker / daemon ownership mode

Goal: support multiple MCP clients without multiple CDP owners.

Tasks:

• Define an OpenChrome broker process that owns Chrome/CDP lifecycle.
• Let stdio MCP adapters either run embedded broker mode when they are the only owner, or forward requests to an existing local broker.
• Reuse Streamable HTTP where possible for multi-client access.
• Add broker discovery via lock metadata or a local endpoint file.
• Ensure authentication/tenant identity is preserved when forwarding from clients to broker.
• Keep a no-daemon fallback for simple single-client stdio usage.

Acceptance criteria:

• Claude and Codex can both connect to one broker without spawning two Chrome controllers.
• Only the broker has direct Puppeteer/CDP browser ownership for a shared profile.
• Client disconnect does not kill shared Chrome if other clients still have leases.

3. Central target ownership registry

Goal: make tab ownership explicit and cross-client safe.

Tasks:

• Introduce shared registry entries: targetId, sessionId, clientId, workerId, laneId, contextName, createdAt, lastActivityAt, leaseExpiresAt, cleanupPolicy.
• Ensure all target creation paths register ownership before exposing target IDs.
• Ensure external/popup targets inherit ownership from opener when appropriate.
• Prevent cleanup from closing targets owned by another active lease.
• Add lease expiry and orphan recovery for clients that disconnect mid-task.
• Expose registry state through MCP resources/diagnostics without leaking sensitive URLs unless authorized.

Acceptance criteria:

• Two clients using one broker can work in different tabs without either closing the other's target.
• TTL and memory-pressure cleanup respect active leases.
• Reconnect validates targets against the central registry and evicts only truly stale entries.

4. Per-target command queues with cross-target parallelism

Goal: preserve ordering where required without turning all browser work into global serial execution.

Tasks:

• Queue commands per target/tab.
• Allow commands for different targets to run concurrently under global resource limits.
• Serialize target lifecycle operations: create, close, detach, reassign, cleanup.
• Add cancellation semantics for queued work when a target closes or lease expires.
• Record queue wait time and execution time in metrics.

Acceptance criteria:

• Two sessions navigating different tabs can run concurrently.
• Two commands against the same tab execute in order.
• Closing a tab cancels or rejects queued commands for that tab with a clear error.

5. Setup/config support for explicit isolation

Goal: make safe topology easy for users who want independent MCP processes.

Tasks:

• Add setup/config options for --port, --user-data-dir, and possibly --profile-name / --profile-scope.
• Generate host-specific config for Claude, Codex, OpenCode, and HTTP daemon with those args included.
• Add documented presets:
  • shared broker/profile;
  • isolated per-host profiles;
  • CI/headless profile;
  • development/testing profile.
• Warn when multiple host configs point to the same port/profile without broker mode.

Acceptance criteria:

• Users can configure Claude and Codex to separate 9222/9223 profiles from setup commands.
• Users can configure Claude and Codex to share one broker intentionally.
• Setup no longer silently encourages accidental duplicate controllers.

6. Doctor and live diagnostics

Goal: make this failure mode obvious before a disconnect occurs.

Tasks:

• Add openchrome doctor checks for:
  • number of running openchrome-mcp processes;
  • processes sharing the same port;
  • processes sharing the same userDataDir;
  • stale ~/.codex/mcp.json entries;
  • conflicting Claude/Codex/OpenCode registrations;
  • Chrome endpoints with multiple unmanaged controllers.
• Add an oc_connection_health field for owner/broker identity and duplicate-controller warnings.
• Include suggested commands for safe cleanup and reconfiguration.

Acceptance criteria:

• Doctor reports a clear warning when two OpenChrome MCP servers target the same Chrome.
• Health output names whether the current process is owner, broker client, or unsafe secondary attach.

7. Cleanup and lifecycle hardening

Goal: make shared Chrome robust under crashes, reconnects, and memory pressure.

Tasks:

• Separate client disconnect from browser shutdown.
• Make oc_stop broker-aware and lease-aware.
• Ensure memory-pressure cleanup uses lease priority and target ownership.
• Make reconnect a broker-level operation, not something every client performs independently.
• Persist enough state to recover target ownership after transient CDP reconnect.
• Add tests for owner crash, client crash, Chrome crash, stale target, and lease expiry.

Acceptance criteria:

• One client disconnecting does not drop tools or close tabs for other active clients.
• Broker reconnect does not make client sessions lose ownership when targets still exist.
• Cleanup cannot close another active session's leased target except under documented emergency policy.

8. Documentation and migration guide

Goal: set user expectations around safe parallelism.

Tasks:

• Document the difference between:
  • one broker with many sessions;
  • many MCP processes with isolated profiles;
  • unsafe many-MCP-one-Chrome direct attach.
• Add recipes for Claude + Codex + OMX coexistence.
• Add troubleshooting for “MCP disconnected” and “81 tools disappeared” symptoms.
• Explain memory tradeoffs: one Chrome/many tabs saves shared browser overhead, but tab renderers still consume memory.

Acceptance criteria:

• Users can choose a topology intentionally.
• The default docs no longer imply that multiple clients should independently run openchrome serve --auto-launch against the same Chrome.

Updated open questions

1. Should broker mode become the default for all setup commands, or remain opt-in until mature?
2. What is the exact local discovery mechanism for an existing broker: lock file, endpoint file, HTTP daemon, or all of the above?
3. Which operations require global serialization, and which can safely run cross-target in parallel?
4. What lease expiry policy is safe for long-running agent tasks without leaking tabs forever?
5. How should stdio-only hosts forward to a broker while preserving MCP semantics and auth identity?
6. Should shared-profile mode allow multiple tenants by default, or require explicit trust configuration?
7. What should be the default topology when both Claude and Codex are installed on the same machine?

Open questions

1. What is the minimum compatibility matrix before a feature is called portable?
2. Which optional MCP capabilities are allowed to be enhancement-only?
3. When does a pilot feature graduate to core?
4. What is the public name for the verified memory loop?
5. How should OpenChrome describe Hermes/OpenClaw integration without coupling to either host?
6. Which benchmark axis is required before updating README headline claims?
7. Which artifacts should become required in PR descriptions for changes that affect host portability?
8. Which shared-profile broker milestones are required before multi-client shared Chrome becomes a documented default?