[STG-2080] feat: add managed local Chrome args (browserbase#2201)

## Summary

Port of
[browserbase/cli#127](browserbase/cli#127) into
the stagehand monorepo, where the browse CLI now lives at `packages/cli`
(package `browse`). The old `browserbase/cli` repo is deprecated.

Adds a managed-local Chrome launch-arg surface to the browse CLI,
matching the Playwright / Puppeteer / chrome-launcher convention (three
repeatable/boolean flags, no JSON):

- `--chrome-arg <flag>` (repeatable) — append a launch arg on top of
Chrome's defaults
- `--ignore-default-chrome-arg <flag>` (repeatable) — drop a specific
default arg
- `--no-default-chrome-args` — launch without any of Chrome's default
args

All three are **managed-local only** (rejected with `--remote` / `--cdp`
/ `--auto-connect`); `--no-default-chrome-args` and
`--ignore-default-chrome-arg` are mutually exclusive. Args are threaded
into Stagehand `localBrowserLaunchOptions` (`args` /
`ignoreDefaultArgs`) and tracked as part of daemon target compatibility
so session reuse respects them.

**Usage note:** because `--chrome-arg` / `--ignore-default-chrome-arg`
are variadic, pass the URL *before* them (`browse open <url> --local
--chrome-arg=--foo`) or terminate flags with `--`. The CLI prints a
clear error pointing this out otherwise.

## Files

- `packages/cli/src/lib/driver/flags.ts` — new flag definitions
- `packages/cli/src/lib/driver/mode.ts` — flag parsing, conflict checks,
`managedLocalTarget(...)` / `resolveChromeArgs(...)` helpers, chrome-arg
target-compatibility comparison (merged on top of the monorepo's
`getRemote()` / async `stagehandOptions` refactor)
- `packages/cli/src/lib/driver/command-cli.ts` —
`hasChromeArgFlags(flags)` wired into `hasExplicitDriverTarget` /
`hasModeOnlyFlag`
- `packages/cli/src/lib/driver/types.ts` — `chromeArgs` /
`ignoreDefaultArgs` / `noDefaultChromeArgs` on the managed-local target
- `packages/cli/src/lib/driver/session-manager.ts` — forwards args into
`localBrowserLaunchOptions`
- `packages/cli/README.md` — flag table rows + example
- `packages/cli/tests/driver-{commands,foundation}.test.ts` — parsing,
conflicts, compatibility, pass-through
- `.changeset/managed-local-chrome-args.md` — `browse` patch

## E2E Test Matrix

| Command / flow | Observed output | Confidence / sufficiency |
| --- | --- | --- |
| `npx turbo run build --filter=browse` | `4 successful, 4 total` —
builds `@browserbasehq/stagehand` (with `gen-version` +
`build-dom-scripts` prereqs) then `browse`; `tsc` + oclif manifest clean
| Proves the merged driver files compile against the monorepo's
refactored core. |
| `pnpm test` (in `packages/cli`) | `Test Files 15 passed (15)` / `Tests
212 passed (212)` — incl. the new managed-local chrome-arg foundation
tests and driver-command parsing/conflict/compatibility tests | Unit +
contract coverage for flag parsing, conflict rules, daemon target
compatibility/reuse, and Stagehand option pass-through. |
| `pnpm lint` (in `packages/cli`) | `prettier --check` clean, `eslint`
clean, `tsc --noEmit` clean | Format / lint / typecheck green on the
ported + merged files. |

Linear: https://linear.app/browserbase/issue/STG-2080

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds managed-local Chrome launch-arg flags to the `browse` CLI so users
can add or override Chrome defaults. Fulfills Linear STG-2080 and
ensures daemon session reuse only when these options match.

- **New Features**
- New flags: `--chrome-arg <flag>` (repeatable),
`--ignore-default-chrome-arg <flag>` (repeatable),
`--no-default-chrome-args`.
- Managed-local only; rejected with `--remote`, `--cdp`,
`--auto-connect`, or implicit remote mode.
- `--no-default-chrome-args` and `--ignore-default-chrome-arg` are
mutually exclusive.
- Flags flow into `localBrowserLaunchOptions` (`args`,
`ignoreDefaultArgs`) for `@browserbasehq/stagehand`.
- Daemon session reuse now compares these args; chrome-arg flags also
mark an explicit driver target.

- **Refactors**
- Use Node’s `isDeepStrictEqual` to compare `chromeArgs` and
`ignoreDefaultArgs` for target compatibility.
- Restored `browse` patch changeset for the decoupled release workflow.

<sup>Written for commit e3a9531.
Summary will update on new commits.</sup>

<a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2201?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>

<!-- End of auto-generated description by cubic. -->

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: shrey150

.changeset/managed-local-chrome-args.md

@@ -0,0 +1,5 @@
+---
+"browse": patch
+---
+
+Add Chrome launch arg flags for managed local browser sessions: `--chrome-arg <flag>` (repeatable) appends launch args on top of Chrome's defaults, `--ignore-default-chrome-arg <flag>` (repeatable) drops specific default args, and `--no-default-chrome-args` launches without any of Chrome's defaults.

packages/cli/README.md

@@ -57,10 +57,14 @@ Every driver command accepts the same flags to pick where the browser runs. Mix
 | `--auto-connect` | Auto-discover and attach to a local Chrome with remote debugging enabled |
 | `--cdp <url\|port>` | Attach directly to a CDP endpoint (port, `http(s)://`, or `ws(s)://`) |
 | `--target-id <id>` | Select a specific CDP target when attaching to an existing browser |
+| `--chrome-arg <flag>` | Append a Chrome launch arg on top of the defaults (repeatable, managed-local only) |
+| `--ignore-default-chrome-arg <flag>` | Drop a specific Chrome default launch arg (repeatable, managed-local only) |
+| `--no-default-chrome-args` | Launch without any of Chrome's default args (managed-local only) |
 
 ```bash
 browse open https://example.com                 # default target
 browse open https://example.com --local --headed
+browse open https://example.com --local --headed --chrome-arg=--no-focus-on-navigate
 browse open https://example.com --remote
 browse open https://example.com --auto-connect
 browse open https://example.com --cdp 9222

packages/cli/src/lib/driver/command-cli.ts

@@ -4,26 +4,36 @@ import type { DriverCommandName } from "./commands/types.js";
 import {
   autoConnectFlag,
   cdpFlag,
+  chromeArgFlag,
   headedFlag,
   headlessFlag,
+  ignoreDefaultChromeArgFlag,
   localFlag,
+  noDefaultChromeArgsFlag,
   remoteFlag,
   sessionFlag,
   sessionName,
   targetIdFlag,
 } from "./flags.js";
 import { getDriverStatus } from "./daemon/client.js";
-import { resolveConnectionTarget, type DriverModeFlags } from "./mode.js";
+import {
+  hasChromeArgFlags,
+  resolveConnectionTarget,
+  type DriverModeFlags,
+} from "./mode.js";
 import type { ConnectionTarget } from "./types.js";
 import { outputJson } from "../output.js";
 import { runDriverCommandWithTarget } from "./runtime.js";
 
 export const driverCommandFlags = {
   "auto-connect": autoConnectFlag,
   cdp: cdpFlag,
+  "chrome-arg": chromeArgFlag,
   headed: headedFlag,
   headless: headlessFlag,
+  "ignore-default-chrome-arg": ignoreDefaultChromeArgFlag,
   local: localFlag,
+  "no-default-chrome-args": noDefaultChromeArgsFlag,
   remote: remoteFlag,
   session: sessionFlag,
   "target-id": targetIdFlag,
@@ -89,6 +99,7 @@ export function hasExplicitDriverTarget(flags: DriverFlags): boolean {
       flags.remote ||
       flags["auto-connect"] ||
       flags.cdp ||
+      hasChromeArgFlags(flags) ||
       flags["target-id"] ||
       flags.headed ||
       flags.headless,
@@ -100,6 +111,7 @@ function hasModeOnlyFlag(flags: DriverFlags): boolean {
     (flags.local || flags.remote) &&
       !flags["auto-connect"] &&
       !flags.cdp &&
+      !hasChromeArgFlags(flags) &&
       !flags["target-id"] &&
       !flags.headed &&
       !flags.headless &&

packages/cli/src/lib/driver/flags.ts

@@ -40,6 +40,25 @@ export const targetIdFlag = Flags.string({
   helpValue: "<target-id>",
 });
 
+export const chromeArgFlag = Flags.string({
+  description:
+    "Add a Chrome launch arg for managed local sessions. Repeatable.",
+  helpValue: "<flag>",
+  multiple: true,
+});
+
+export const ignoreDefaultChromeArgFlag = Flags.string({
+  description:
+    "Drop one of Chrome's default launch args for managed local sessions. Repeatable.",
+  helpValue: "<flag>",
+  multiple: true,
+});
+
+export const noDefaultChromeArgsFlag = Flags.boolean({
+  description:
+    "Launch managed local Chrome without any of its default launch args.",
+});
+
 export function sessionName(value?: string): string {
   return value ?? process.env.BROWSE_SESSION ?? "default";
 }

packages/cli/src/lib/driver/mode.ts

@@ -1,3 +1,5 @@
+import { isDeepStrictEqual } from "node:util";
+
 import { fail } from "../errors.js";
 import { getRemote } from "./remote-binding.js";
 import { resolveWsTarget } from "./resolve-ws.js";
@@ -6,13 +8,21 @@ import type { ConnectionTarget } from "./types.js";
 export interface DriverModeFlags {
   "auto-connect"?: boolean;
   cdp?: string;
+  "chrome-arg"?: string[];
   headed?: boolean;
   headless?: boolean;
+  "ignore-default-chrome-arg"?: string[];
   local?: boolean;
+  "no-default-chrome-args"?: boolean;
   remote?: boolean;
   "target-id"?: string;
 }
 
+interface ResolvedChromeArgs {
+  args?: string[];
+  ignoreDefaultArgs?: boolean | string[];
+}
+
 function resolveHeadless(
   flags: Pick<DriverModeFlags, "headed" | "headless">,
 ): boolean {
@@ -25,12 +35,28 @@ function resolveHeadless(
   return true;
 }
 
+export function hasChromeArgFlags(flags: DriverModeFlags): boolean {
+  return chromeArgFlagsInUse(flags).length > 0;
+}
+
+function chromeArgFlagsInUse(flags: DriverModeFlags): string[] {
+  const names: string[] = [];
+  if (flags["chrome-arg"]?.length) names.push("--chrome-arg");
+  if (flags["ignore-default-chrome-arg"]?.length)
+    names.push("--ignore-default-chrome-arg");
+  if (flags["no-default-chrome-args"]) names.push("--no-default-chrome-args");
+  return names;
+}
+
 export async function resolveConnectionTarget(
   flags: DriverModeFlags,
 ): Promise<ConnectionTarget> {
+  const chromeArgFlags = chromeArgFlagsInUse(flags);
+
   if (flags.cdp) {
     failOnConflictingFlags("--cdp", [
       flags["auto-connect"] ? "--auto-connect" : null,
+      ...chromeArgFlags,
       flags.local ? "--local" : null,
       flags.remote ? "--remote" : null,
       flags.headed ? "--headed" : null,
@@ -49,6 +75,7 @@ export async function resolveConnectionTarget(
 
   if (flags["auto-connect"]) {
     failOnConflictingFlags("--auto-connect", [
+      ...chromeArgFlags,
       flags.local ? "--local" : null,
       flags.remote ? "--remote" : null,
       flags.headed ? "--headed" : null,
@@ -63,26 +90,42 @@ export async function resolveConnectionTarget(
 
   if (flags.remote) {
     failOnConflictingFlags("--remote", [
+      ...chromeArgFlags,
       flags.headed ? "--headed" : null,
       flags.headless ? "--headless" : null,
     ]);
     return (await getRemote()).resolveExplicitRemoteTarget(flags);
   }
 
   if (flags.local) {
-    return { kind: "managed-local", headless: resolveHeadless(flags) };
+    return managedLocalTarget(resolveHeadless(flags), resolveChromeArgs(flags));
   }
 
   const autoRemote = (await getRemote()).autoSelectRemoteTarget();
   if (autoRemote) {
     failOnConflictingFlags("remote mode", [
+      ...chromeArgFlags,
       flags.headed ? "--headed" : null,
       flags.headless ? "--headless" : null,
     ]);
     return autoRemote;
   }
 
-  return { kind: "managed-local", headless: resolveHeadless(flags) };
+  return managedLocalTarget(resolveHeadless(flags), resolveChromeArgs(flags));
+}
+
+function managedLocalTarget(
+  headless: boolean,
+  chromeArgs: ResolvedChromeArgs,
+): ConnectionTarget {
+  return {
+    ...(chromeArgs.args?.length ? { chromeArgs: chromeArgs.args } : {}),
+    ...(chromeArgs.ignoreDefaultArgs !== undefined
+      ? { ignoreDefaultArgs: chromeArgs.ignoreDefaultArgs }
+      : {}),
+    kind: "managed-local",
+    headless,
+  };
 }
 
 function failOnConflictingFlags(
@@ -96,15 +139,57 @@ function failOnConflictingFlags(
     fail(`${flag} cannot be combined with ${conflicts.join(", ")}.`);
 }
 
+function resolveChromeArgs(flags: DriverModeFlags): ResolvedChromeArgs {
+  const args = flags["chrome-arg"]?.filter((arg) => arg.length > 0);
+  const ignoreDefaults = flags["ignore-default-chrome-arg"]?.filter(
+    (arg) => arg.length > 0,
+  );
+  const noDefaults = flags["no-default-chrome-args"] === true;
+
+  if (noDefaults && ignoreDefaults?.length) {
+    fail(
+      "--no-default-chrome-args cannot be combined with --ignore-default-chrome-arg.",
+    );
+  }
+
+  const resolved: ResolvedChromeArgs = {};
+  if (args?.length) resolved.args = args;
+  if (noDefaults) {
+    resolved.ignoreDefaultArgs = true;
+  } else if (ignoreDefaults?.length) {
+    resolved.ignoreDefaultArgs = ignoreDefaults;
+  }
+  return resolved;
+}
+
 export function targetsCompatible(
   left: ConnectionTarget,
   right: ConnectionTarget,
 ): boolean {
   if (left.kind !== right.kind) return false;
   if (left.kind === "managed-local" && right.kind === "managed-local")
-    return left.headless === right.headless;
+    return (
+      left.headless === right.headless &&
+      chromeArgsEqual(left.chromeArgs, right.chromeArgs) &&
+      ignoreDefaultArgsEqual(left.ignoreDefaultArgs, right.ignoreDefaultArgs)
+    );
   if (left.kind === "cdp" && right.kind === "cdp") {
     return left.endpoint === right.endpoint && left.targetId === right.targetId;
   }
   return true;
 }
+
+function chromeArgsEqual(left?: string[], right?: string[]): boolean {
+  return isDeepStrictEqual(left ?? [], right ?? []);
+}
+
+function ignoreDefaultArgsEqual(
+  left?: boolean | string[],
+  right?: boolean | string[],
+): boolean {
+  if (left === true || right === true) return left === right;
+  return chromeArgsEqual(
+    Array.isArray(left) ? left : undefined,
+    Array.isArray(right) ? right : undefined,
+  );
+}

packages/cli/src/lib/driver/session-manager.ts

@@ -279,6 +279,10 @@ export class DriverSessionManager {
         disablePino: true,
         env: "LOCAL",
         localBrowserLaunchOptions: {
+          ...(target.chromeArgs?.length ? { args: target.chromeArgs } : {}),
+          ...(target.ignoreDefaultArgs !== undefined
+            ? { ignoreDefaultArgs: target.ignoreDefaultArgs }
+            : {}),
           headless: target.headless,
         },
         verbose: 0,

packages/cli/src/lib/driver/types.ts

@@ -1,5 +1,10 @@
 export type ConnectionTarget =
-  | { kind: "managed-local"; headless: boolean }
+  | {
+      chromeArgs?: string[];
+      ignoreDefaultArgs?: boolean | string[];
+      kind: "managed-local";
+      headless: boolean;
+    }
   | { kind: "remote" }
   | { kind: "auto-connect" }
   | { kind: "cdp"; endpoint: string; targetId?: string };

packages/cli/tests/driver-commands.test.ts

@@ -59,6 +59,19 @@ describe("driver commands", () => {
     expect(hasExplicitDriverTarget({ headed: true })).toBe(true);
     expect(hasExplicitDriverTarget({ headless: true })).toBe(true);
     expect(hasExplicitDriverTarget({ cdp: "9222" })).toBe(true);
+    expect(
+      hasExplicitDriverTarget({
+        "chrome-arg": ["--no-focus-on-navigate"],
+      }),
+    ).toBe(true);
+    expect(
+      hasExplicitDriverTarget({
+        "ignore-default-chrome-arg": ["--enable-automation"],
+      }),
+    ).toBe(true);
+    expect(hasExplicitDriverTarget({ "no-default-chrome-args": true })).toBe(
+      true,
+    );
   });
 
   it("reuses an existing daemon when a broad mode flag matches", async () => {