STG-1672: Add --connect flag to browse CLI for existing Browserbase sessions

[shrey150]

Summary

• Adds a global --connect <session-id> flag to the browse CLI that connects to an existing Browserbase session instead of creating a new one
• Uses Stagehand core's existing browserbaseSessionID support with keepAlive: true so the session stays alive after the CLI disconnects
• Follows the same state-file pattern as --context-id (writes session ID to /tmp/browse-{session}.connect, daemon reads it during initialization)

Test procedure

# 1. Sync cookies
node cookie-sync.mjs --domains github.com
# → Session ID: 3ee737d4-237f-4557-a1ca-09a3d5dcbaf2

# 2. Connect and browse (dev build)
browse --connect 3ee737d4-... open https://github.com/notifications  ✅
browse eval "..."  ✅

Tests completed

• browse --connect <id> open ... in local mode → errors with "only supported in remote mode"
• browse --connect <id> open --context-id <ctx> ... → errors with mutual exclusion message
• --connect writes session ID to connect file before daemon start
• Commands without --connect clear stale connect file
• browse status output includes browserbaseSessionId field
• Manual: browse --connect <valid-bb-session> open https://example.com connects and navigates
• Manual: browse stop disconnects without killing the BB session

🤖 Generated with Claude Code

Fixes STG-1672

---

Summary by cubic

Adds a --connect <session-id> flag to the browse CLI to attach to an existing Browserbase session instead of creating a new one, leaving the session running after the CLI exits. Implements STG-1672.

• New Features
  • New global --connect <session-id> for browse to attach to an existing Browserbase session
  • Remote mode only; errors in local mode
  • Mutually exclusive with --context-id
  • Persists the session ID to /tmp/browse-{session}.connect; clears when unused and restarts the daemon if the ID changes
  • Uses browserbaseSessionID with keepAlive: true so the session persists after disconnect
  • browse status now includes a browserbaseSessionId field
  • Minor release for @browserbasehq/browse-cli

^{Written for commit aff1bad. Summary will update on new commits. Review in cubic}

[changeset-bot]

🦋 Changeset detected

Latest commit: 7a14528

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]

No issues found across 3 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant User
    participant CLI as CLI (Client Process)
    participant FS as Local Filesystem (/tmp)
    participant Daemon as CLI Daemon Process
    participant SH as Stagehand Core
    participant BB as Browserbase API

    Note over User,BB: Request Flow with --connect flag

    User->>CLI: browse --connect <id> open <url>
    
    alt Mode Validation
        CLI->>CLI: Check browse mode (env)
        opt Mode is LOCAL
            CLI-->>User: Error: --connect only supported in remote mode
        end
        
        opt --context-id also provided
            CLI-->>User: Error: Mutually exclusive with --connect
        end
    end

    alt NEW: Handle Session Connection State
        CLI->>FS: NEW: Write <session-id> to browse-{session}.connect
    else Command without --connect
        CLI->>FS: CHANGED: Unlink browse-{session}.connect (clear stale)
    end

    CLI->>Daemon: ensureDaemon()
    
    Note over Daemon: Initialization (if not running)
    
    Daemon->>FS: NEW: Read browse-{session}.connect
    FS-->>Daemon: session-id (if exists)

    Daemon->>SH: NEW: Initialize Stagehand
    Note over SH: Pass browserbaseSessionID & keepAlive: true
    
    SH->>BB: Connect to existing Session ID
    BB-->>SH: Session socket attached

    CLI->>Daemon: sendCommand("open", url)
    Daemon->>SH: page.goto(url)
    SH-->>Daemon: Navigation complete
    Daemon-->>CLI: Success
    CLI-->>User: Command finished

    Note over User,BB: browse status (Information Flow)

    User->>CLI: browse status
    CLI->>Daemon: getStatus()
    Daemon->>FS: NEW: Read browse-{session}.connect
    FS-->>Daemon: session-id
    Daemon-->>CLI: Return status + browserbaseSessionId
    CLI-->>User: JSON output with browserbaseSessionId

Loading

[shrey150]

Sister PR for skills docs: browserbase/skills#53