feat(cli): add --chrome-arg flag for extra Chromium flags (fixes #2148)

[kagura-agent]

Summary

Add a repeatable --chrome-arg global flag to the browse CLI so users can pass extra Chromium flags to the local browser.

Closes #2148

Problem

The browse CLI's headed mode steals window focus on every command because there is no way to pass Chromium flags like --no-focus-on-navigate or --disable-backgrounding-occluded-windows. The core LocalBrowserLaunchOptionsSchema already supports an args array, and launch/local.ts already spreads opts.args into chromeFlags — but the CLI layer never exposes this to end users.

Changes

packages/cli/src/local-strategy.ts

• Add args?: string[] to the CLI's LocalBrowserLaunchOptions interface
• Add extraArgs?: string[] to ResolveLocalStrategyOptions
• Forward extraArgs into localLaunchOptions for the isolated and isolated-fallback paths (CDP-attach paths are unaffected — args are irrelevant when attaching to an existing browser)

packages/cli/src/index.ts

• Add chromeArg?: string[] to GlobalOpts
• Add --chrome-arg <arg> repeatable option to the program
• Thread chrome args through runCommand → ensureDaemon → daemon spawn → runDaemon → resolveLocalStrategy
• Also forward args in the direct --ws connection path

.changeset/expose-chrome-args-cli.md

• Patch changeset for the CLI package

Usage

# Suppress focus stealing in headed mode
browse open https://example.com --headed \
  --chrome-arg=--no-focus-on-navigate \
  --chrome-arg=--disable-backgrounding-occluded-windows

# Pass any Chromium flag
browse snapshot --chrome-arg=--disable-gpu

Testing

• Code review: every changed line traces to the issue
• The flag plumbing was verified by tracing all code paths: runCommand → ensureDaemon (spawn with --chrome-arg forwarded) → runDaemon → resolveLocalStrategy → localLaunchOptions.args → core's launchLocalChrome → chromeFlags array
• No existing tests are affected (the change is additive — new optional parameter with empty-array default everywhere)

---

Summary by cubic

Added a repeatable --chrome-arg flag to the browse CLI to pass extra Chromium flags to the local browser. This helps stop window focus stealing in headed mode and allows other Chrome tuning.

• New Features
  • --chrome-arg <arg> is repeatable and forwarded through the daemon, direct --ws connections, and local strategy resolution.
  • Flags are injected into local launch options (args), enabling options like --no-focus-on-navigate and --disable-backgrounding-occluded-windows.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 0b57504

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	Patch

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

[github-actions]

This PR is from an external contributor and must be approved by a stagehand team member with write access before CI can run.
Approving the latest commit mirrors it into an internal PR owned by the approver.
If new commits are pushed later, the internal PR stays open but is marked stale until someone approves the latest external commit and refreshes it.

[cubic-dev-ai]

1 issue found across 3 files

Confidence score: 3/5

• There is a concrete regression risk in packages/cli/src/index.ts: the daemon compatibility check does not account for --chrome-arg changes, so users can silently keep running with stale Chromium flags.
• Given the issue’s medium severity (6/10) and high confidence (8/10), this carries real user-facing behavior risk even though the change set is small.
• This is likely fixable without broad redesign, but merge confidence is moderate until daemon reuse logic reflects flag changes.
• Pay close attention to packages/cli/src/index.ts - ensure daemon compatibility/restart logic includes --chrome-arg so updated Chromium flags are applied.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/cli/src/index.ts">

<violation number="1" location="packages/cli/src/index.ts:1514">
P2: Daemon compatibility check ignores `--chrome-arg` changes, silently reusing an existing daemon with stale Chromium flags.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant User as CLI User
    participant CLI as CLI Entry (index.ts)
    participant Daemon as Daemon Process
    participant LocalStrategy as Local Strategy (local-strategy.ts)
    participant Core as Core Launch (launchLocalChrome)

    Note over User,Core: NEW: --chrome-arg flag flow

    User->>CLI: browse open --chrome-arg=--no-focus-on-navigate --chrome-arg=--disable-gpu
    CLI->>CLI: Parse --chrome-arg as repeatable string[]

    alt Direct --ws connection
        CLI->>CLI: Build localBrowserLaunchOptions with chromeArgs
        Note over CLI: args: ["--no-focus-on-navigate", "--disable-gpu"]
        CLI->>Core: init() with localBrowserLaunchOptions.args
    else Daemon path
        CLI->>Daemon: spawn daemon with --chrome-arg forwarded
        Daemon->>Daemon: runDaemon(session, headless, chromeArgs)
        Daemon->>LocalStrategy: resolveLocalStrategy({ extraArgs: chromeArgs })
        
        alt Isolated strategy
            LocalStrategy->>LocalStrategy: Merge extraArgs into localLaunchOptions.args
            LocalStrategy-->>Daemon: localLaunchOptions with args array
        else Isolated-fallback strategy
            LocalStrategy->>LocalStrategy: Merge extraArgs into localLaunchOptions.args
            LocalStrategy-->>Daemon: localLaunchOptions with args array
        else CDP-attach strategy
            Note over LocalStrategy: extraArgs ignored (attaching to existing browser)
            LocalStrategy-->>Daemon: No args in localLaunchOptions
        end
        
        Daemon->>Core: launchLocalChrome(localLaunchOptions)
        Core->>Core: Spread args into chromeFlags[]
        Core-->>Daemon: Chrome launched with extra flags
        Daemon-->>CLI: Ready for commands
        CLI->>Daemon: sendCommand with chromeArgs for restart handling
    end

    Note over User,Core: Failure handling preserves chromeArgs
    alt Daemon restart on failure
        Daemon->>Daemon: ensureDaemon(session, headless, chromeArgs)
        Daemon-->>CLI: Restarted with same chrome flags
    end

Loading

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Daemon compatibility check ignores --chrome-arg changes, silently reusing an existing daemon with stale Chromium flags.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/cli/src/index.ts, line 1514:

<comment>Daemon compatibility check ignores `--chrome-arg` changes, silently reusing an existing daemon with stale Chromium flags.</comment>

<file context>
@@ -1509,7 +1511,7 @@ async function stopDaemonAndCleanup(session: string): Promise<void> {
 }
 
-async function ensureDaemon(session: string, headless: boolean): Promise<void> {
+async function ensureDaemon(session: string, headless: boolean, chromeArgs: string[] = []): Promise<void> {
   const wantMode = await getDesiredMode(session);
   assertModeSupported(wantMode);
</file context>

[kagura-agent]

Re: cubic-dev-ai's daemon compatibility concern — valid point that the daemon reuse check doesn't account for --chrome-arg changes. However, this is a scope expansion beyond the current PR (which adds --chrome-arg passthrough). The existing daemon reuse logic also doesn't track other flag changes like --headless. Happy to address daemon compatibility in a follow-up PR if the team wants it.