STG-1668: browse env local auto-discovers existing Chrome via CDP by shrey150 · Pull Request #1886 · browserbase/stagehand

shrey150 · 2026-03-25T00:59:10Z

Summary

browse env local now auto-discovers an already-running Chrome with remote debugging enabled (via DevToolsActivePort files and common port probing), attaching to it instead of always launching an isolated browser
Falls back to isolated launch when no debuggable Chrome is found — keeps the command reliable
Added --isolated flag to force clean isolated browser (old behavior)
Added positional CDP target argument: browse env local 9222 or browse env local ws://...
browse status now reports localStrategy, localSource, resolvedCdpUrl, and fallbackReason

Sister PR: browserbase/skills#54

Test plan

All 44 existing tests pass
browse env local with Chrome running + --remote-debugging-port=9222 → attaches to existing Chrome
browse env local without debuggable Chrome → falls back to isolated launch
browse env local --isolated → always launches clean browser
browse env local 9222 → persists CDP strategy targeting 127.0.0.1:9222
browse status shows local strategy details
browse env remote → unchanged

🤖 Generated with Claude Code

changeset-bot · 2026-03-25T00:59:16Z

🦋 Changeset detected

Latest commit: 1863297

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@browserbasehq/browse-cli	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

cubic-dev-ai

2 issues found across 6 files

Confidence score: 3/5

There is a concrete user-impacting risk in packages/cli/src/resolve-ws.ts: falling back to ws://127.0.0.1:<port> without /devtools/browser can produce invalid CDP websocket targets and failed attaches.
packages/cli/src/index.ts also has a high-confidence endpoint validation issue: plain TCP reachability is treated as a valid websocket target while hardcoding /devtools/browser, which can allow invalid auto-discovery results.
Given both issues are severity 7/10 with high confidence, this looks like a meaningful regression risk in CDP connection behavior rather than a merge-blocking system-wide break.
Pay close attention to packages/cli/src/resolve-ws.ts and packages/cli/src/index.ts - CDP fallback/discovery endpoint construction and validation may accept invalid targets and break attach flows.

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/resolve-ws.ts">

<violation number="1" location="packages/cli/src/resolve-ws.ts:23">
P1: Fallbacking to `ws://127.0.0.1:<port>` is not a valid direct CDP WS endpoint for the no-`/json/version` case; use `/devtools/browser` to avoid failed attaches.</violation>
</file>

<file name="packages/cli/src/index.ts">

<violation number="1" location="packages/cli/src/index.ts:368">
P1: CDP auto-discovery fallback can accept invalid endpoints because it hardcodes `/devtools/browser` and treats plain TCP connectivity as a valid websocket target.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User
    participant CLI as Browse CLI
    participant Config as Local Config (FS)
    participant Daemon as Browser Daemon
    participant FS as Chrome User Data (FS)
    participant Chrome as Existing Chrome (CDP)
    participant Isolated as Isolated Browser

    Note over User,Isolated: browse env local Flow

    User->>CLI: browse env local [target] [--isolated]
    CLI->>Config: NEW: writeLocalConfig(strategy, cdpTarget)
    CLI->>Daemon: Restart Daemon

    Daemon->>Config: NEW: readLocalConfig()
    
    alt strategy is "isolated"
        Daemon->>Isolated: Launch new browser
    else strategy is "auto" (default)
        Daemon->>FS: NEW: Scan DevToolsActivePort files
        FS-->>Daemon: Found port(s)
        
        opt No FS matches
            Daemon->>Daemon: NEW: Probe common ports (9222, 9229)
        end

        Daemon->>Chrome: NEW: Probe /json/version (or WS handshake)
        Chrome-->>Daemon: Return webSocketDebuggerUrl

        alt Single valid Chrome found
            Daemon->>Chrome: NEW: Attach via CDP
            Daemon->>Config: NEW: writeLocalInfo(attached-existing)
        else Ambiguous (>1) or None found
            Daemon->>Isolated: NEW: Fallback to isolated launch
            Daemon->>Config: NEW: writeLocalInfo(isolated-fallback)
        end
    else strategy is "cdp" (explicit port/URL)
        Daemon->>Daemon: NEW: resolveWsTarget(target)
        Daemon->>Chrome: Connect to specific endpoint
        Daemon->>Config: NEW: writeLocalInfo(attached-explicit)
    end

    Note over User,Config: browse status Flow

    User->>CLI: browse status
    CLI->>Config: CHANGED: readLocalInfo()
    Config-->>CLI: localSource, resolvedCdpUrl, fallbackReason
    CLI-->>User: Report browser state & strategy details

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

packages/cli/src/resolve-ws.ts

packages/cli/src/index.ts

cubic-dev-ai

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/index.ts">

<violation number="1" location="packages/cli/src/index.ts:415">
P1: The WebSocket verification accepts any response containing "101", which can falsely treat non-upgrade HTTP responses as valid CDP endpoints.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

packages/cli/src/index.ts

Update SKILL.md and REFERENCE.md to reflect new browse env local behavior: auto-discovers existing Chrome with remote debugging, --isolated flag, and explicit CDP target (port or URL). Sister PR to browserbase/stagehand#1886. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

When a bare port number is passed (e.g. `--ws 9222`), resolve the CDP WebSocket URL via `GET http://127.0.0.1:{port}/json/version` with a fallback to `ws://127.0.0.1:{port}`. Full URLs continue to work as-is. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Extract resolveWsTarget into its own module so it can be imported without triggering Commander's program.parse(). Tests cover: - bare port resolved via /json/version - fallback to ws://127.0.0.1:{port} when endpoint is unavailable - ws://, wss://, and http:// URL passthrough Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…via CDP Change browse env local from always launching an isolated browser to preferring an already-debuggable local Chrome. Discovery scans DevToolsActivePort files and common ports, with fallback to isolated. New commands: - browse env local (auto-discover, default) - browse env local --isolated (force clean browser) - browse env local <port|url> (explicit CDP target) browse status now reports localStrategy, localSource, resolvedCdpUrl. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The daemon's shutdown handler and stopDaemonAndCleanup were both calling cleanupStaleFiles which deleted client-written config (local-config, context). Switch both to cleanupDaemonStateFiles so local-config and context survive daemon restarts triggered by browse env switches. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- resolve-ws.ts: fallback URL now includes /devtools/browser path (bare ws://host:port is not a valid CDP endpoint) - verifyCdpWebSocket: replaced TCP-only check with actual HTTP WebSocket upgrade verification (101 Switching Protocols) to avoid accepting non-CDP services as valid endpoints Addresses cubic-dev-ai review feedback. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Use regex /^HTTP\/1\.[01] 101/ instead of response.includes("101") to avoid false positives from non-upgrade responses containing "101". Addresses cubic-dev-ai review feedback. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The --ws port resolution was an earlier commit that's part of the larger auto-discover feature. One minor changeset covers both. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

pirate · 2026-03-27T18:45:10Z

packages/cli/README.md

+To make your Chrome discoverable, launch it with `--remote-debugging-port`:
+
+```bash
+google-chrome --remote-debugging-port=9222
+```


Suggested change

To make your Chrome discoverable, launch it with `--remote-debugging-port`:

```bash

google-chrome --remote-debugging-port=9222

```

To make your Chrome discoverable:

1. Open chrome://inspect/#remote-debugging

2. Check the box "Allow remote debugging for this browser instance"

3. Re-run the CLI and it will auto-connect!

For more information, see:

https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session

I would recommend that people use the newer method instead.

Because google-chrome --remote-debugging-port=9222 does not work with a default data dir.

Addressed in 65c74f7f — replaced the --remote-debugging-port=9222 instructions with the chrome://inspect/#remote-debugging method and linked the Chrome DevTools blog post. Thanks for the suggestion!

pirate

Approved with that one suggestion.

Replace the `google-chrome --remote-debugging-port=9222` instructions with the newer chrome://inspect/#remote-debugging approach per reviewer feedback, since the flag doesn't work with the default data dir. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…spect Second occurrence in the Local Browser Strategies section. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

cubic-dev-ai bot reviewed Mar 25, 2026

View reviewed changes

packages/cli/src/resolve-ws.ts Outdated Show resolved Hide resolved

packages/cli/src/index.ts Show resolved Hide resolved

cubic-dev-ai bot reviewed Mar 25, 2026

View reviewed changes

packages/cli/src/index.ts Outdated Show resolved Hide resolved

shrey150 mentioned this pull request Mar 25, 2026

docs(browser): browse env local auto-discovery browserbase/skills#54

Open

shrey150 and others added 8 commits March 25, 2026 22:59

style: format with prettier

e2c2d69

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chore: consolidate changesets into single minor

dc8adda

The --ws port resolution was an earlier commit that's part of the larger auto-discover feature. One minor changeset covers both. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

shrey150 force-pushed the shrey/cli-local-auto-discover branch from cebffac to dc8adda Compare March 26, 2026 05:59

shrey150 and others added 2 commits March 27, 2026 00:02

fix: remove stray merge conflict marker in cli/src/index.ts

7b7ae49

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: format index.ts with prettier

6661e98

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

pirate requested changes Mar 27, 2026

View reviewed changes

pirate reviewed Mar 27, 2026

View reviewed changes

pirate approved these changes Mar 27, 2026

View reviewed changes

shrey150 and others added 2 commits March 27, 2026 14:51

docs(cli): replace remaining --remote-debugging-port with chrome://in…

1863297

…spect Second occurrence in the Local Browser Strategies section. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

pirate approved these changes Mar 27, 2026

View reviewed changes

shrey150 merged commit bd2a9cf into main Mar 27, 2026
32 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

STG-1668: browse env local auto-discovers existing Chrome via CDP#1886

STG-1668: browse env local auto-discovers existing Chrome via CDP#1886
shrey150 merged 12 commits intomainfrom
shrey/cli-local-auto-discover

shrey150 commented Mar 25, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Mar 25, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

Uh oh!

pirate Mar 27, 2026 •

edited

Loading

Uh oh!

shrey150 Mar 27, 2026

Uh oh!

pirate left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-To make your Chrome discoverable, launch it with `--remote-debugging-port`:
-```bash
-google-chrome --remote-debugging-port=9222
-```
+To make your Chrome discoverable:
+. Open chrome://inspect/#remote-debugging
+. Check the box "Allow remote debugging for this browser instance"
+. Re-run the CLI and it will auto-connect!
+For more information, see:
+https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session

Conversation

shrey150 commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

changeset-bot bot commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pirate Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shrey150 Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

pirate left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

shrey150 commented Mar 25, 2026 •

edited

Loading

changeset-bot bot commented Mar 25, 2026 •

edited

Loading

pirate Mar 27, 2026 •

edited

Loading