Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

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.py
index 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_dir
self._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.py
index 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:
# doctor
subparsers.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')
+
# config
config_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 deprecation
if 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 1
if now - agent_entry.get('last_active', 0) > 300:
- # Expired — remove it
agents.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_active
agent_entry['last_active'] = now
agents_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 exclusivity
if 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 args
diff --git a/skills/browser-use/SKILL.md b/skills/browser-use/SKILL.md
index 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 confirm
6. **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 browser
browser-use --headed open <url> # Visible Chromium window
browser-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 profile
browser-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.trycloudfla
browser-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 |