[feat]: forward ignoreDefaultArgs to chrome-launcher

[seanmcguire12]

thanks @CalebBarnes for the contribution! (original PR: #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 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

---

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.

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

---

[changeset-bot]

🦋 Changeset detected

Latest commit: e04da99

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@browserbasehq/stagehand	Minor
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server-v3	Patch
@browserbasehq/stagehand-server-v4	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

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
stagehand	🟢 Ready	View Preview	May 15, 2026, 8:23 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[cubic-dev-ai]

No issues found across 5 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant User as Consumer Code
    participant V3 as V3 Class
    participant Local as launchLocalChrome()
    participant ChromeL as chrome-launcher
    participant Chrome as Chrome Browser

    Note over User,Chrome: New: ignoreDefaultArgs forwarding flow

    User->>V3: new Stagehand({ localBrowserLaunchOptions: { ignoreDefaultArgs } })
    V3->>V3: Store localBrowserLaunchOptions

    User->>V3: stagehand.init()
    V3->>V3: Read localBrowserLaunchOptions

    alt ignoreDefaultArgs is true
        V3->>Local: launchLocalChrome({ ignoreDefaultArgs: true })
        Local->>Local: Set ignoreDefaultFlags = true
        Local->>ChromeL: launch({ ignoreDefaultFlags: true })
        ChromeL->>Chrome: Start with NO default flags
    else ignoreDefaultArgs is string[]
        V3->>Local: launchLocalChrome({ ignoreDefaultArgs: ["--disable-extensions"] })
        Local->>Local: Set ignoreDefaultFlags = true
        Local->>Local: Get Launcher.defaultFlags()
        Local->>Local: Filter out excluded flags
        Local->>Local: Prepend kept defaults to chromeFlags
        Local->>ChromeL: launch({ chromeFlags, ignoreDefaultFlags: true })
        ChromeL->>Chrome: Start with filtered defaults + Stagehand flags
    else ignoreDefaultArgs is false/undefined
        V3->>Local: launchLocalChrome({ ignoreDefaultArgs: undefined })
        Local->>ChromeL: launch({ ignoreDefaultFlags: false })
        ChromeL->>Chrome: Start with ALL default flags
    end

    Chrome-->>ChromeL: Browser instance
    ChromeL-->>Local: LaunchedChrome
    Local-->>V3: Chrome instance with WS endpoint
    V3-->>User: Stagehand initialized

Loading

_{Re-trigger cubic}

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

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/core/lib/v3/launch/local.ts">

<violation number="1" location="packages/core/lib/v3/launch/local.ts:32">
P1: `ignoreDefaultArgs` currently strips Stagehand default flags, but it should only affect chrome-launcher defaults. This can silently remove required Stagehand launch flags when `ignoreDefaultArgs` is set.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.
Re-trigger cubic}