Context
The browse CLI (v0.7.3, npm install -g browse) uses Stagehand under the hood. When running in --headed mode on macOS, every CLI command (browse snapshot, browse click, browse get url, etc.) causes the Chromium window to steal focus from whatever application the user is currently working in.
The DX problem
The primary use case for --headed mode is developing and debugging browser automation flows from an AI coding agent (Claude Code, Cursor, etc.). The agent drives the browser via browse commands while the developer works in parallel — reading code, reviewing output, or doing other tasks. Every focus-steal interrupts the developer's flow.
This is a solved problem in Playwright itself: Playwright's headed mode does not steal focus on every page interaction. The difference is that Playwright passes Chrome flags like --disable-background-timer-throttling and avoids bringToFront() calls during normal interaction.
Root cause
In session-manager.js, the localBrowserLaunchOptions only passes headless:
localBrowserLaunchOptions: {
headless: target.headless,
},There's no way to pass additional Chromium args (e.g., --no-focus-on-navigate) or Playwright launch options through the browse CLI.
Proposed fix
Expose a way to pass additional Chrome args or Playwright launch options in local headed mode. Options:
- A
--chrome-arg flag on browse commands: browse open https://example.com --local --headed --chrome-arg=--no-focus-on-navigate
- A config file or env var for default local launch options
- Better defaults — if headed mode is primarily for agent-driven automation, suppress focus-stealing by default (opt-in to focus with a flag instead)
Option 3 would give the best out-of-box DX for the agent use case, which is the primary audience for this tool.
Environment
- browse v0.7.3
- macOS (Darwin 25.5.0, arm64)
- Node v26.0.0
Context
The
browseCLI (v0.7.3,npm install -g browse) uses Stagehand under the hood. When running in--headedmode on macOS, every CLI command (browse snapshot,browse click,browse get url, etc.) causes the Chromium window to steal focus from whatever application the user is currently working in.The DX problem
The primary use case for
--headedmode is developing and debugging browser automation flows from an AI coding agent (Claude Code, Cursor, etc.). The agent drives the browser viabrowsecommands while the developer works in parallel — reading code, reviewing output, or doing other tasks. Every focus-steal interrupts the developer's flow.This is a solved problem in Playwright itself: Playwright's headed mode does not steal focus on every page interaction. The difference is that Playwright passes Chrome flags like
--disable-background-timer-throttlingand avoidsbringToFront()calls during normal interaction.Root cause
In
session-manager.js, thelocalBrowserLaunchOptionsonly passesheadless:There's no way to pass additional Chromium args (e.g.,
--no-focus-on-navigate) or Playwright launch options through the browse CLI.Proposed fix
Expose a way to pass additional Chrome args or Playwright launch options in local headed mode. Options:
--chrome-argflag on browse commands:browse open https://example.com --local --headed --chrome-arg=--no-focus-on-navigateOption 3 would give the best out-of-box DX for the agent use case, which is the primary audience for this tool.
Environment