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

[shrey150]

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]

🦋 Changeset detected

Latest commit: dc8adda

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

Loading

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

[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.}