Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
feat: add connect command + --agent flag, decouple multi-agent from Chrome
ShawnPana73a926caa6cb
diff --git a/browser_use/skill_cli/daemon.py b/browser_use/skill_cli/daemon.pyindex 56a9dbd94..6526866b7 100644--- a/browser_use/skill_cli/daemon.py+++ b/browser_use/skill_cli/daemon.py@@ -163,7 +163,7 @@ class Daemon:from browser_use.skill_cli.utils import get_home_dirself._tab_ownership = TabOwnershipManager(bs)- self._tab_ownership.set_agents_file(get_home_dir() / 'agents.json')+ self._tab_ownership.set_agents_file(get_home_dir() / f'{self.session}.agents.json')# Register initial tabs with tab ownership (no event bus)if bs.session_manager:diff --git a/browser_use/skill_cli/main.py b/browser_use/skill_cli/main.pyindex 734201c8c..8beec121d 100755--- a/browser_use/skill_cli/main.py+++ b/browser_use/skill_cli/main.py@@ -100,12 +100,20 @@ if _get_subcommand() == 'init':init_main()sys.exit(0)-# Handle 'register' command — assigns an agent index for multi-agent --connect mode+# Handle 'register' command — assigns an agent index for multi-agent mode (per-session)if _get_subcommand() == 'register':_home = os.environ.get('BROWSER_USE_HOME')_home_dir = Path(_home).expanduser() if _home else Path.home() / '.browser-use'_home_dir.mkdir(parents=True, exist_ok=True)- agents_file = _home_dir / 'agents.json'+ # Resolve session name from --session flag or env+ _session = 'default'+ for i, arg in enumerate(sys.argv):+ if arg == '--session' and i + 1 < len(sys.argv):+ _session = sys.argv[i + 1]+ break+ if _session == 'default':+ _session = os.environ.get('BROWSER_USE_SESSION', 'default')+ agents_file = _home_dir / f'{_session}.agents.json'agents = {}if agents_file.exists():try:@@ -655,10 +663,16 @@ Setup:)parser.add_argument('--connect',+ action='store_true',+ default=False,+ help='(Deprecated) Use "browser-use connect" instead',+ )+ parser.add_argument(+ '--agent',nargs=1,- metavar='AGENT_INDEX',+ metavar='INDEX',default=None,- help='Connect to running Chrome via CDP with agent index (run "browser-use register" first)',+ help='Multi-agent mode with tab isolation (run "browser-use register" first)',)parser.add_argument('--session', default=None, help='Session name (default: "default")')parser.add_argument('--json', action='store_true', help='Output as JSON')@@ -691,6 +705,9 @@ Setup:# doctorsubparsers.add_parser('doctor', help='Check browser-use installation and dependencies')+ # connect (to local Chrome)+ subparsers.add_parser('connect', help='Connect to running Chrome via CDP')+# configconfig_p = subparsers.add_parser('config', help='Manage CLI configuration')config_sub = config_p.add_subparsers(dest='config_command')@@ -1387,12 +1404,46 @@ def main() -> int:print('No active browser session')return 0- # Resolve --connect to agent_id + CDP URL- agent_id = '__shared__'+ # Handle --connect deprecationif args.connect:- agent_id = args.connect[0]- # Validate agent index against registry- agents_file = _get_home_dir() / 'agents.json'+ print('Note: --connect has been replaced.', file=sys.stderr)+ print(' To connect to Chrome: browser-use connect', file=sys.stderr)+ print(' Then run commands: browser-use open <url>', file=sys.stderr)+ print(' For multi-agent: browser-use --agent INDEX open <url>', file=sys.stderr)+ return 1++ # Handle connect command (discover local Chrome, start daemon)+ if args.command == 'connect':+ from browser_use.skill_cli.utils import discover_chrome_cdp_url++ try:+ cdp_url = discover_chrome_cdp_url()+ except RuntimeError as e:+ print(f'Error: {e}', file=sys.stderr)+ return 1++ ensure_daemon(args.headed, None, cdp_url=cdp_url, session=session, explicit_config=True)+ response = send_command('connect', {}, session=session)++ if args.json:+ print(json.dumps(response))+ else:+ if response.get('success'):+ data = response.get('data', {})+ print(f'status: {data.get("status", "unknown")}')+ if 'cdp_url' in data:+ print(f'cdp_url: {data["cdp_url"]}')+ else:+ print(f'Error: {response.get("error")}', file=sys.stderr)+ return 1+ return 0++ # Resolve --agent to agent_id+ agent_id = '__shared__'+ if args.agent:+ agent_id = args.agent[0]+ # Validate agent index against per-session registry+ agents_file = _get_home_dir() / f'{session}.agents.json'agents = {}if agents_file.exists():try:@@ -1405,42 +1456,23 @@ def main() -> int:print(f'Error: Agent {agent_id} not registered. Run \'browser-use register\' first.', file=sys.stderr)return 1if now - agent_entry.get('last_active', 0) > 300:- # Expired — remove itagents.pop(agent_id, None)agents_file.write_text(json.dumps(agents))print(f'Error: Agent {agent_id} session expired. Run \'browser-use register\' to get a new agent ID.', file=sys.stderr)return 1- # Update last_activeagent_entry['last_active'] = nowagents_file.write_text(json.dumps(agents))- # Mutual exclusivity: --connect, --cdp-url, and --profile- if args.connect and args.cdp_url:- print('Error: --connect and --cdp-url are mutually exclusive', file=sys.stderr)- return 1- if args.connect and args.profile:- print('Error: --connect and --profile are mutually exclusive', file=sys.stderr)- return 1+ # Mutual exclusivityif args.cdp_url and args.profile:print('Error: --cdp-url and --profile are mutually exclusive', file=sys.stderr)return 1- # Resolve --connect to a CDP URL- if args.connect:- from browser_use.skill_cli.utils import discover_chrome_cdp_url-- try:- args.cdp_url = discover_chrome_cdp_url()- except RuntimeError as e:- print(f'Error: {e}', file=sys.stderr)- return 1-# One-time legacy migration_migrate_legacy_files()# Ensure daemon is running- # Only restart on config mismatch if the user explicitly passed config flags- explicit_config = any(flag in sys.argv for flag in ('--headed', '--profile', '--cdp-url', '--connect'))+ explicit_config = any(flag in sys.argv for flag in ('--headed', '--profile', '--cdp-url'))ensure_daemon(args.headed, args.profile, args.cdp_url, session=session, explicit_config=explicit_config)# Build params from argsdiff --git a/skills/browser-use/SKILL.md b/skills/browser-use/SKILL.mdindex 6a750f07f..8302ef06d 100644--- a/skills/browser-use/SKILL.md+++ b/skills/browser-use/SKILL.md@@ -20,32 +20,34 @@ For setup details, see https://github.com/browser-use/browser-use/blob/main/brow**Default: connect to the user's existing Chrome browser.** This preserves their logins, cookies, and open tabs.-1. **Register**: `INDEX=$(browser-use register)` — get an agent index (once per session)-2. **Navigate**: `browser-use --connect $INDEX open <url>` — opens in a new tab in the user's Chrome-3. **Inspect**: `browser-use --connect $INDEX state` — returns clickable elements with indices-4. **Interact**: use indices from state (`browser-use --connect $INDEX click 5`, `browser-use --connect $INDEX input 3 "text"`)-5. **Verify**: `browser-use --connect $INDEX state` or `browser-use --connect $INDEX screenshot` to confirm+1. **Connect**: `browser-use connect` — discover and connect to running Chrome (one-time)+2. **Navigate**: `browser-use open <url>` — opens in a new tab+3. **Inspect**: `browser-use state` — returns clickable elements with indices+4. **Interact**: use indices from state (`browser-use click 5`, `browser-use input 3 "text"`)+5. **Verify**: `browser-use state` or `browser-use screenshot` to confirm6. **Repeat**: browser stays open between commands-If `--connect` fails (Chrome not running with remote debugging), fall back to `browser-use --headed open <url>` which launches a fresh Chromium.+If `connect` fails (Chrome not running with remote debugging), fall back to `browser-use --headed open <url>` which launches a fresh Chromium.## Browser Modes```bash-# Preferred: connect to user's existing Chrome (requires remote debugging enabled)-INDEX=$(browser-use register)-browser-use --connect $INDEX open <url> # Connect to running Chrome with agent index+# Preferred: connect to user's existing Chrome (one-time setup)+browser-use connect # Discover and connect to running Chrome-# Fallback: launch a new browser+# Cloud browser (zero-config)+browser-use cloud connect # Provision cloud browser++# Launch a new browserbrowser-use --headed open <url> # Visible Chromium windowbrowser-use open <url> # Headless Chromium# Other modes-browser-use --profile "Default" open <url> # Real Chrome with Default profile+browser-use --profile "Default" open <url> # Real Chrome with Default profilebrowser-use --cdp-url ws://localhost:9222/... open <url> # Connect via explicit CDP URL```-`--connect`, `--cdp-url`, and `--profile` are mutually exclusive.+After connecting, all commands go to that browser — no flags needed. `--cdp-url` and `--profile` are mutually exclusive.## Commands@@ -186,8 +188,8 @@ browser-use --profile "Default" open https://github.com # Already logged in### Connecting to Existing Chrome```bash-INDEX=$(browser-use register) # Get agent index first-browser-use --connect $INDEX open https://example.com # Connect with agent index+browser-use connect # Discover and connect (one-time)+browser-use open https://example.com # Then use normally```Requires Chrome with remote debugging enabled. Falls back to probing ports 9222/9229.@@ -199,22 +201,23 @@ browser-use tunnel 3000 # → https://abc.trycloudflabrowser-use open https://abc.trycloudflare.com # Browse the tunnel```-## Multi-Agent (--connect mode)+## Multi-Agent (--agent)-Multiple agents can share one Chrome browser via `--connect`. Each agent gets its own tab — other agents can't interfere.+Multiple agents can share one browser via `--agent`. Each agent gets its own tab — other agents can't interfere. Works with any browser mode (connect, cloud connect, profile, headless).-**Setup**: Register once, then pass the index with every `--connect` command:+**Setup**: Connect once, register agents, then pass `--agent` with every command:```bash+browser-use connect # or cloud connect, or --profile, etc.INDEX=$(browser-use register) # → prints "1"-browser-use --connect $INDEX open <url> # Navigate in agent's own tab-browser-use --connect $INDEX state # Get state from agent's tab-browser-use --connect $INDEX click <element> # Click in agent's tab+browser-use --agent $INDEX open <url> # Navigate in agent's own tab+browser-use --agent $INDEX state # Get state from agent's tab+browser-use --agent $INDEX click <element> # Click in agent's tab```- **Tab locking**: When an agent mutates a tab (click, type, navigate), that tab is locked to it. Other agents get an error if they try to mutate the same tab.- **Read-only access**: `state`, `screenshot`, `get`, and `wait` commands work on any tab regardless of locks.-- **Pre-existing tabs**: Tabs already open in Chrome start unlocked — any agent can claim them.+- **Pre-existing tabs**: Tabs already open start unlocked — any agent can claim them.- **Agent sessions expire** after 5 minutes of inactivity. Run `browser-use register` again to get a new index.- **If you get "Tab is currently in use by another agent"**: do NOT close sessions or force it. Just use `open` to navigate your own tab to the URL you need.- **Never run `browser-use close --all`** when other agents are sharing the browser — it kills everything.@@ -254,7 +257,7 @@ Config stored in `~/.browser-use/config.json`.|--------|-------------|| `--headed` | Show browser window || `--profile [NAME]` | Use real Chrome (bare `--profile` uses "Default") |-| `--connect INDEX` | Connect to running Chrome via CDP with agent index (run `browser-use register` first) |+| `--agent INDEX` | Multi-agent mode with tab isolation (run `browser-use register` first) || `--cdp-url <url>` | Connect via CDP URL (`http://` or `ws://`) || `--session NAME` | Target a named session (default: "default") || `--json` | Output as JSON |