[feat]: forward ignoreDefaultArgs to chrome-launcher (browserbase#2127)

thanks @CalebBarnes for the contribution! (original PR: browserbase#2074)
# why

When running Stagehand locally, chrome-launcher adds its own set of
default flags (e.g. `--disable-extensions`). There's currently no way
for consumers to selectively remove these flags —
`localBrowserLaunchOptions.chromeFlags` can only *add* flags, not remove
chrome-launcher's built-in defaults.

This is needed when users want to run Chrome with extensions enabled, or
need to remove other chrome-launcher defaults for their use case.

# what changed

- Added `ignoreDefaultArgs` option to `LaunchLocalOptions` in `local.ts`
- Forwarded `localBrowserLaunchOptions.ignoreDefaultArgs` from `v3.ts`
through to `launchLocalChrome()`
- When `true`: drops all chrome-launcher defaults (only Stagehand's own
flags and user-supplied `chromeFlags` are used)
- When `string[]`: selectively removes only the listed flags from
chrome-launcher defaults, keeping the rest

This mirrors the behavior of Playwright's

[`ignoreDefaultArgs`](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-option-ignore-default-args)
option.

# test plan

- Verified locally that setting `ignoreDefaultArgs:
["--disable-extensions"]` successfully removes the flag from the
launched Chrome instance (confirmed via `chrome://version/`)
- Verified that other chrome-launcher defaults are preserved when using
the array form
- Verified that `ignoreDefaultArgs: true` drops all chrome-launcher
defaults


<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Adds `ignoreDefaultArgs` to local Chrome launch so you can drop all or
selected default flags from `chrome-launcher` with exact-match control
(including Stagehand defaults), while keeping your own `args`.

- **New Features**
- Added `ignoreDefaultArgs` to `LaunchLocalOptions` and moved flag
assembly into `launchLocalChrome()`, forwarding to `chrome-launcher` via
`ignoreDefaultFlags`.
- `true` drops all `chrome-launcher` defaults; `string[]` removes only
exact-matched defaults and re-adds the rest from
`Launcher.defaultFlags()`. Stagehand defaults and user `args` stay
unless explicitly listed.

<sup>Written for commit e04da99.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/2127?utm_source=github">Review
in cubic</a></sup>

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



---------

---------

Co-authored-by: Caleb Barnes <caleb.d.barnes@gmail.com>
Co-authored-by: Caleb Barnes <CalebBarnes@users.noreply.github.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-6) <noreply@mastra.ai>

Author: 3 people

.changeset/forward-ignore-default-args.md

@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": minor
+---
+
+Add `ignoreDefaultArgs` option to selectively remove chrome-launcher's built-in default flags (e.g. `--disable-extensions`) when running locally

packages/core/lib/v3/launch/local.ts

@@ -1,17 +1,20 @@
-import { launch, LaunchedChrome } from "chrome-launcher";
+import { launch, Launcher, LaunchedChrome } from "chrome-launcher";
 import WebSocket from "ws";
 import { ConnectionTimeoutError } from "../types/public/sdkErrors.js";
+import type { LocalBrowserLaunchOptions } from "../types/public/index.js";
 
-interface LaunchLocalOptions {
-  chromePath?: string;
-  chromeFlags?: string[];
-  headless?: boolean;
-  userDataDir?: string;
-  port?: number;
-  connectTimeoutMs?: number;
+interface LaunchLocalOptions extends LocalBrowserLaunchOptions {
   handleSIGINT?: boolean;
 }
 
+const STAGEHAND_DEFAULT_FLAGS = [
+  "--remote-allow-origins=*",
+  "--no-first-run",
+  "--no-default-browser-check",
+  "--disable-dev-shm-usage",
+  "--site-per-process",
+];
+
 export async function launchLocalChrome(
   opts: LaunchLocalOptions,
 ): Promise<{ ws: string; chrome: LaunchedChrome }> {
@@ -23,22 +26,58 @@ export async function launchLocalChrome(
     Math.ceil(connectTimeoutMs / connectionPollInterval),
   );
   const headless = opts.headless ?? false;
+  const ignoredDefaults = Array.isArray(opts.ignoreDefaultArgs)
+    ? opts.ignoreDefaultArgs
+    : null;
+  const stagehandDefaultFlags =
+    opts.ignoreDefaultArgs === true
+      ? []
+      : ignoredDefaults
+        ? STAGEHAND_DEFAULT_FLAGS.filter((f) => !ignoredDefaults.includes(f))
+        : [...STAGEHAND_DEFAULT_FLAGS];
   const chromeFlags = [
+    ...stagehandDefaultFlags,
     headless ? "--headless=new" : undefined,
-    "--remote-allow-origins=*",
-    "--no-first-run",
-    "--no-default-browser-check",
-    "--disable-dev-shm-usage",
-    "--site-per-process",
-    ...(opts.chromeFlags ?? []),
+    opts.devtools ? "--auto-open-devtools-for-tabs" : undefined,
+    opts.locale ? `--lang=${opts.locale}` : undefined,
+    opts.viewport?.width && opts.viewport?.height
+      ? `--window-size=${opts.viewport.width},${opts.viewport.height + 87}`
+      : undefined,
+    typeof opts.deviceScaleFactor === "number"
+      ? `--force-device-scale-factor=${Math.max(0.1, opts.deviceScaleFactor)}`
+      : undefined,
+    opts.hasTouch ? "--touch-events=enabled" : undefined,
+    opts.ignoreHTTPSErrors ? "--ignore-certificate-errors" : undefined,
+    opts.proxy?.server ? `--proxy-server=${opts.proxy.server}` : undefined,
+    opts.proxy?.bypass ? `--proxy-bypass-list=${opts.proxy.bypass}` : undefined,
+    ...(opts.args ?? []),
   ].filter((f): f is string => typeof f === "string");
 
+  // Handle ignoreDefaultArgs: selectively remove chrome-launcher's built-in
+  // defaults while keeping Stagehand's own flags (already in chromeFlags).
+  let ignoreDefaultFlags = false;
+  if (opts.ignoreDefaultArgs === true) {
+    ignoreDefaultFlags = true;
+  } else if (
+    Array.isArray(opts.ignoreDefaultArgs) &&
+    opts.ignoreDefaultArgs.length > 0
+  ) {
+    // Tell chrome-launcher to skip ALL its defaults, then re-add the ones
+    // the user did NOT ask to exclude.
+    ignoreDefaultFlags = true;
+    const excludeArgs = opts.ignoreDefaultArgs;
+    const clDefaults = Launcher.defaultFlags?.() ?? [];
+    const kept = clDefaults.filter((f) => !excludeArgs.includes(f));
+    chromeFlags.unshift(...kept);
+  }
+
   const chrome = await launch({
-    chromePath: opts.chromePath,
+    chromePath: opts.executablePath,
     chromeFlags,
     port: opts.port,
     userDataDir: opts.userDataDir,
     handleSIGINT: opts.handleSIGINT,
+    ignoreDefaultFlags,
     connectionPollInterval,
     maxConnectionRetries,
   });

packages/core/lib/v3/v3.ts

@@ -944,62 +944,14 @@ export class V3 {
             createdTemp = true;
           }
 
-          // Build chrome flags
-          const defaults = [
-            "--remote-allow-origins=*",
-            "--no-first-run",
-            "--no-default-browser-check",
-            "--disable-dev-shm-usage",
-            "--site-per-process",
-          ];
-          let chromeFlags: string[];
-          const ignore = lbo.ignoreDefaultArgs;
-          if (ignore === true) {
-            // drop defaults
-            chromeFlags = [];
-          } else if (Array.isArray(ignore)) {
-            chromeFlags = defaults.filter(
-              (f) => !ignore.some((ex) => f.includes(ex)),
-            );
-          } else {
-            chromeFlags = [...defaults];
-          }
-
-          // headless handled by launchLocalChrome
-          if (lbo.devtools) chromeFlags.push("--auto-open-devtools-for-tabs");
-          if (lbo.locale) chromeFlags.push(`--lang=${lbo.locale}`);
           if (!lbo.viewport) {
             lbo.viewport = DEFAULT_VIEWPORT;
           }
-          if (lbo.viewport?.width && lbo.viewport?.height) {
-            chromeFlags.push(
-              `--window-size=${lbo.viewport.width},${lbo.viewport.height + 87}`, // Added pixels to the window to account for the address bar
-            );
-          }
-          if (typeof lbo.deviceScaleFactor === "number") {
-            chromeFlags.push(
-              `--force-device-scale-factor=${Math.max(0.1, lbo.deviceScaleFactor)}`,
-            );
-          }
-          if (lbo.hasTouch) chromeFlags.push("--touch-events=enabled");
-          if (lbo.ignoreHTTPSErrors)
-            chromeFlags.push("--ignore-certificate-errors");
-          if (lbo.proxy?.server)
-            chromeFlags.push(`--proxy-server=${lbo.proxy.server}`);
-          if (lbo.proxy?.bypass)
-            chromeFlags.push(`--proxy-bypass-list=${lbo.proxy.bypass}`);
-
-          // add user-supplied args last
-          if (Array.isArray(lbo.args)) chromeFlags.push(...lbo.args);
 
           const keepAlive = this.keepAlive === true;
           const { ws, chrome } = await launchLocalChrome({
-            chromePath: lbo.executablePath,
-            chromeFlags,
-            port: lbo.port,
-            headless: lbo.headless,
+            ...lbo,
             userDataDir,
-            connectTimeoutMs: lbo.connectTimeoutMs,
             handleSIGINT: !keepAlive,
           });
           if (keepAlive) {

packages/core/tests/unit/launch-local-ignore-default-args.test.ts

@@ -0,0 +1,196 @@
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeEach,
+  afterEach,
+  type Mock,
+} from "vitest";
+
+/**
+ * Unit tests for the `ignoreDefaultArgs` option in `launchLocalChrome`.
+ *
+ * Strategy: mock `chrome-launcher` and `ws` so `launchLocalChrome` returns
+ * immediately, then assert the flags passed to `chrome-launcher.launch()`.
+ */
+
+const FAKE_WS_URL = "ws://127.0.0.1:9222/devtools/browser/fake";
+const FAKE_CHROME_LAUNCHER_DEFAULTS = [
+  "--disable-extensions",
+  "--disable-component-extensions-with-background-pages",
+  "--disable-background-networking",
+  "--disable-sync",
+  "--mute-audio",
+];
+
+vi.mock("chrome-launcher", () => ({
+  launch: vi.fn().mockResolvedValue({
+    port: 9222,
+    kill: vi.fn(),
+    pid: 12345,
+  }),
+  Launcher: {
+    defaultFlags: () => [...FAKE_CHROME_LAUNCHER_DEFAULTS],
+  },
+}));
+
+// Mock ws: the probe calls `new WebSocket(url)` then `.once("open", cb)`.
+// Use EventEmitter so "open" fires after the listener is attached.
+vi.mock("ws", async () => {
+  const { EventEmitter } =
+    await vi.importActual<typeof import("node:events")>("node:events");
+
+  class MockWebSocket extends EventEmitter {
+    constructor() {
+      super();
+      process.nextTick(() => this.emit("open"));
+    }
+    terminate() {}
+  }
+  return { default: MockWebSocket, WebSocket: MockWebSocket };
+});
+
+let launchMock: Mock;
+
+beforeEach(async () => {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ webSocketDebuggerUrl: FAKE_WS_URL }),
+    }),
+  );
+
+  const chromeLauncher = await import("chrome-launcher");
+  launchMock = chromeLauncher.launch as Mock;
+  launchMock.mockClear();
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+async function getLaunchArgs(
+  opts: Record<string, unknown>,
+): Promise<{ chromeFlags: string[]; ignoreDefaultFlags: boolean }> {
+  const { launchLocalChrome } = await import("../../lib/v3/launch/local.js");
+  await launchLocalChrome(opts);
+  return launchMock.mock.calls[0][0];
+}
+
+describe("launchLocalChrome ignoreDefaultArgs", () => {
+  it("does not set ignoreDefaultFlags when ignoreDefaultArgs is omitted", async () => {
+    const args = await getLaunchArgs({});
+    expect(args.ignoreDefaultFlags).toBe(false);
+  });
+
+  it("does not set ignoreDefaultFlags when ignoreDefaultArgs is false", async () => {
+    const args = await getLaunchArgs({ ignoreDefaultArgs: false });
+    expect(args.ignoreDefaultFlags).toBe(false);
+  });
+
+  it("sets ignoreDefaultFlags=true when ignoreDefaultArgs is true", async () => {
+    const args = await getLaunchArgs({ ignoreDefaultArgs: true });
+    expect(args.ignoreDefaultFlags).toBe(true);
+    expect(args.chromeFlags).not.toContain("--remote-allow-origins=*");
+    expect(args.chromeFlags).not.toContain("--no-first-run");
+    // No chrome-launcher defaults should be prepended
+    for (const flag of FAKE_CHROME_LAUNCHER_DEFAULTS) {
+      expect(args.chromeFlags).not.toContain(flag);
+    }
+  });
+
+  it("selectively removes only the listed flag", async () => {
+    const args = await getLaunchArgs({
+      ignoreDefaultArgs: ["--disable-extensions"],
+    });
+
+    expect(args.ignoreDefaultFlags).toBe(true);
+    expect(args.chromeFlags).not.toContain("--disable-extensions");
+
+    // Other defaults should be preserved (exact match, not substring)
+    expect(args.chromeFlags).toContain(
+      "--disable-component-extensions-with-background-pages",
+    );
+    expect(args.chromeFlags).toContain("--disable-background-networking");
+    expect(args.chromeFlags).toContain("--disable-sync");
+    expect(args.chromeFlags).toContain("--mute-audio");
+  });
+
+  it("uses exact matching, not substring matching", async () => {
+    // "--disable-component" is a substring of
+    // "--disable-component-extensions-with-background-pages",
+    // but exact matching should NOT remove it
+    const args = await getLaunchArgs({
+      ignoreDefaultArgs: ["--disable-component"],
+    });
+
+    expect(args.chromeFlags).toContain(
+      "--disable-component-extensions-with-background-pages",
+    );
+    expect(args.chromeFlags).toContain("--disable-extensions");
+    expect(args.chromeFlags).toContain("--mute-audio");
+  });
+
+  it("uses exact matching for Stagehand defaults too", async () => {
+    const args = await getLaunchArgs({
+      ignoreDefaultArgs: ["--no-first"],
+    });
+
+    expect(args.chromeFlags).toContain("--no-first-run");
+    expect(args.chromeFlags).toContain("--remote-allow-origins=*");
+  });
+
+  it("preserves all defaults when ignoreDefaultArgs is an empty array", async () => {
+    const args = await getLaunchArgs({ ignoreDefaultArgs: [] });
+    expect(args.ignoreDefaultFlags).toBe(false);
+  });
+
+  it("keeps Stagehand's own flags when selectively removing defaults", async () => {
+    const args = await getLaunchArgs({
+      ignoreDefaultArgs: ["--mute-audio"],
+    });
+
+    // Spot-check a couple of Stagehand's flags — not the full list,
+    // so this test doesn't break if Stagehand adds/removes its own flags.
+    expect(args.chromeFlags).toContain("--remote-allow-origins=*");
+    expect(args.chromeFlags).toContain("--no-first-run");
+
+    expect(args.chromeFlags).not.toContain("--mute-audio");
+    expect(args.chromeFlags).toContain("--disable-extensions");
+  });
+
+  it("merges user chromeFlags with re-added defaults", async () => {
+    const args = await getLaunchArgs({
+      args: ["--custom-flag"],
+      ignoreDefaultArgs: ["--disable-sync"],
+    });
+
+    expect(args.chromeFlags).toContain("--custom-flag");
+    expect(args.chromeFlags).not.toContain("--disable-sync");
+    // Other defaults should still be present
+    expect(args.chromeFlags).toContain("--disable-extensions");
+  });
+
+  it("does not deduplicate when user chromeFlags overlap with defaults", async () => {
+    const args = await getLaunchArgs({
+      args: ["--disable-sync"],
+      ignoreDefaultArgs: ["--mute-audio"],
+    });
+
+    // "--disable-sync" appears in both user flags and re-added defaults
+    const count = args.chromeFlags.filter((f) => f === "--disable-sync").length;
+    expect(count).toBe(2);
+  });
+
+  it("selectively removes Stagehand defaults by exact match", async () => {
+    const args = await getLaunchArgs({
+      ignoreDefaultArgs: ["--no-first-run"],
+    });
+
+    expect(args.chromeFlags).not.toContain("--no-first-run");
+    expect(args.chromeFlags).toContain("--remote-allow-origins=*");
+    expect(args.chromeFlags).toContain("--disable-extensions");
+  });
+});