From e1cd4727f43c4524cc23e51af102b5993aeb0638 Mon Sep 17 00:00:00 2001
From: Shrey Pandya <shrey@browserbase.com>
Date: Wed, 25 Mar 2026 00:02:14 -0700
Subject: [PATCH] docs(browser): document browse env local auto-discovery

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>
---
 skills/browser/REFERENCE.md | 11 +++++++++--
 skills/browser/SKILL.md     | 16 ++++++++++++----
 2 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/skills/browser/REFERENCE.md b/skills/browser/REFERENCE.md
index 71827a4..c7b0c04 100644
--- a/skills/browser/REFERENCE.md
+++ b/skills/browser/REFERENCE.md
@@ -272,16 +272,23 @@ Check whether the daemon is running, its connection details, and current environ
 browse status
 ```
 
-#### `env [local|remote]`
+#### `env [local|remote] [cdpTarget] [--isolated]`
 
 Show or switch the browser environment. Without arguments, prints the current environment. With an argument, stops the running daemon and restarts in the specified environment. The switch is sticky — subsequent commands stay in the chosen environment until you switch again or run `browse stop`.
 
+`browse env local` auto-discovers an already-running Chrome with remote debugging enabled (scans `DevToolsActivePort` files and probes common ports like 9222). Falls back to launching an isolated browser if no debuggable Chrome is found.
+
 ```bash
 browse env                               # print current environment
-browse env local                         # switch to local Chrome
+browse env local                         # auto-discover local Chrome, fallback to isolated
+browse env local --isolated              # force clean isolated browser (skip discovery)
+browse env local 9222                    # attach to CDP target on port 9222
+browse env local ws://host:port/path     # attach to explicit CDP WebSocket URL
 browse env remote                        # switch to Browserbase (requires API keys)
 ```
 
+`browse status` reports `localStrategy`, `localSource`, `resolvedCdpUrl`, and `fallbackReason` when in local mode.
+
 #### `newpage [url]`
 
 Create a new tab, optionally navigating to a URL.
diff --git a/skills/browser/SKILL.md b/skills/browser/SKILL.md
index 3c4e652..9963a02 100644
--- a/skills/browser/SKILL.md
+++ b/skills/browser/SKILL.md
@@ -33,7 +33,9 @@ which browse || npm install -g @browserbasehq/browse-cli
 The CLI automatically selects between local and remote browser environments based on available configuration:
 
 ### Local mode (default)
-- Uses local Chrome — no API keys needed
+- Auto-discovers an already-running Chrome with remote debugging enabled and attaches to it
+- Falls back to launching an isolated Chrome if no debuggable browser is found
+- No API keys needed
 - Best for: development, simple pages, trusted sites with no bot protection
 
 ### Remote mode (Browserbase)
@@ -92,9 +94,11 @@ browse wait <type> [arg]                 # Wait for: load, selector, timeout
 ### Session management
 ```bash
 browse stop                              # Stop the browser daemon
-browse status                            # Check daemon status (includes env)
+browse status                            # Check daemon status (includes env and local strategy)
 browse env                               # Show current environment (local or remote)
-browse env local                         # Switch to local Chrome
+browse env local                         # Auto-discover local Chrome, fallback to isolated
+browse env local --isolated              # Force clean isolated browser (skip auto-discovery)
+browse env local <port|url>              # Attach to specific CDP target
 browse env remote                        # Switch to Browserbase (requires API keys)
 browse pages                             # List all open tabs
 browse tab_switch <index>                # Switch to tab by index
@@ -154,10 +158,14 @@ Don't switch for simple sites (docs, wikis, public APIs, localhost).
 
 ```bash
 browse env remote            # switch to Browserbase
-browse env local             # switch back to local Chrome
+browse env local             # switch back to local (auto-discovers existing Chrome)
+browse env local --isolated  # force a clean isolated browser
+browse env local 9222        # attach to Chrome on specific port
 ```
 
 The switch is sticky until you run `browse stop` or switch again.
 
+`browse env local` auto-discovers a running Chrome with remote debugging enabled (via `DevToolsActivePort` files and common port probing). If no debuggable Chrome is found, it falls back to launching an isolated browser. Use `--isolated` to skip auto-discovery and always get a clean browser.
+
 For detailed examples, see [EXAMPLES.md](EXAMPLES.md).
 For API reference, see [REFERENCE.md](REFERENCE.md).