feat(codex): add the Stagehand marketplace plugin and setup guide

[shrey150]

Codex setup currently leads with a monorepo build and manual MCP configuration. Add a repository marketplace plugin that installs through codex plugin marketplace add browserbase/stagehand and codex plugin add stagehand@browserbase-stagehand.

The plugin supplies the MCP configuration, browser environment allowlist, and 120-second startup/tool timeouts. Update the public guide, README, and direct-CLI template; credentials stay in the environment. The integration overview now classifies all nine documented hosts by their supported plugin, extension, or SDK/MCP setup route.

Stacked on #2971 for @browserbasehq/stagehand-mcp. Its 0.1.0 release is required before the plugin’s npx command is available. This is a repository marketplace; it does not claim an OpenAI public-directory listing.

E2E Test Matrix

Command / flow	Observed output	Confidence / sufficiency
Plugin creator validator	Passed	Manifest and companion-file validation
Real codex plugin marketplace add and codex plugin add in an isolated profile	Installed stagehand@browserbase-stagehand 0.1.0	Actual local marketplace discovery/install path
codex mcp list --json in that profile	Enabled Stagehand server, expected package command, env allowlist, 120-second timeouts	Codex parses the plugin’s MCP configuration correctly
Packaged server from #2971	Navigation, persistent snapshot, screenshot, shutdown passed against example.com	Shared server runtime; does not claim a full Codex model-loop run or post-release npm download

Documentation validation: a combined snapshot of all nine updated integration guides passed mint validate and mint broken-links --check-anchors --check-redirects --check-snippets.

[changeset-bot]

⚠️ No Changeset found

Latest commit: cfe1e20

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

2 issues found and verified against the latest diff

Confidence score: 4/5

• plugins/stagehand/README.md omits that the MCP child needs its own STAGEHAND_MODEL_NAME and STAGEHAND_MODEL_API_KEY when run JavaScript calls act, extract, or observe, which can leave those operations unconfigured despite Codex credentials; document the required variables.
• packages/docs/v4/integrations/codex.mdx presents Chrome as a prerequisite for Browserbase, even though the remote browser does not need local Chrome; clarify that Chrome is required only for local mode.

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/docs/v4/integrations/codex.mdx">

<violation number="1" location="packages/docs/v4/integrations/codex.mdx:21">
P3: When users choose Browserbase, the facade launches the remote browser and does not need local Chrome. State that Chrome is required only for local mode, otherwise Browserbase users are given an unnecessary prerequisite.</violation>
</file>

<file name="plugins/stagehand/README.md">

<violation number="1" location="plugins/stagehand/README.md:10">
P2: When `run` JavaScript calls `act`, `extract`, or `observe`, this README does not tell users that the MCP child needs separate `STAGEHAND_MODEL_NAME` and `STAGEHAND_MODEL_API_KEY` credentials; Codex’s provider credential is not forwarded by the plugin, so those calls fail without separate configuration. State that plain navigation and inspection need no Stagehand model, while these AI methods do.</violation>
</file>

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

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: When run JavaScript calls act, extract, or observe, this README does not tell users that the MCP child needs separate STAGEHAND_MODEL_NAME and STAGEHAND_MODEL_API_KEY credentials; Codex’s provider credential is not forwarded by the plugin, so those calls fail without separate configuration. State that plain navigation and inspection need no Stagehand model, while these AI methods do.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At plugins/stagehand/README.md, line 10:

<comment>When `run` JavaScript calls `act`, `extract`, or `observe`, this README does not tell users that the MCP child needs separate `STAGEHAND_MODEL_NAME` and `STAGEHAND_MODEL_API_KEY` credentials; Codex’s provider credential is not forwarded by the plugin, so those calls fail without separate configuration. State that plain navigation and inspection need no Stagehand model, while these AI methods do.</comment>

<file context>
@@ -0,0 +1,10 @@
+
+Restart Codex after installation, or open a new task. Requires Node.js 24+, local Chrome or an exported `BROWSERBASE_API_KEY`, and the initial `@browserbasehq/stagehand-mcp@0.1.0` release. This is a repository marketplace plugin, not a claim of listing in OpenAI’s public directory.
+
+The plugin bundles MCP configuration and forwards only the listed browser configuration variables. Keep credentials in your environment instead of the manifest. It preserves one browser across `run`, `snapshot`, and `screenshot` calls.
</file context>

Suggested change

The plugin bundles MCP configuration and forwards only the listed browser configuration variables. Keep credentials in your environment instead of the manifest. It preserves one browser across `run`, `snapshot`, and `screenshot` calls.

The plugin bundles MCP configuration and forwards only the variables listed in its manifest. Keep credentials in your environment instead of the manifest. Plain navigation and inspection need no Stagehand model; configure `STAGEHAND_MODEL_NAME` and `STAGEHAND_MODEL_API_KEY` separately when `run` JavaScript calls `act`, `extract`, or `observe`, because Codex’s provider credential is not forwarded. It preserves one browser across `run`, `snapshot`, and `screenshot` calls.

[cubic-dev-ai]

P3: When users choose Browserbase, the facade launches the remote browser and does not need local Chrome. State that Chrome is required only for local mode, otherwise Browserbase users are given an unnecessary prerequisite.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/integrations/codex.mdx, line 21:

<comment>When users choose Browserbase, the facade launches the remote browser and does not need local Chrome. State that Chrome is required only for local mode, otherwise Browserbase users are given an unnecessary prerequisite.</comment>

<file context>
@@ -3,20 +3,35 @@ title: "Codex"
+
+Restart Codex or open a new task after installing. The plugin uses Codex’s [repository marketplace format](https://developers.openai.com/plugins/build/plugins#add-a-marketplace-from-the-cli); it is not a listing in the universal public directory.
+
+Requires Node.js 24+, an existing Codex login, and local Chrome. To use Browserbase, export `BROWSERBASE_API_KEY` before starting Codex. The plugin passes browser configuration through `env_vars`, so credentials stay out of its manifest. It sets longer startup and tool timeouts for browser work.
+
+Ask Codex to open `https://example.com`, take a snapshot, and report its title. The plugin provides `run`, `snapshot`, and `screenshot` over one persistent MCP connection.
</file context>

Suggested change

	Requires Node.js 24+, an existing Codex login, and local Chrome. To use Browserbase, export `BROWSERBASE_API_KEY` before starting Codex. The plugin passes browser configuration through `env_vars`, so credentials stay out of its manifest. It sets longer startup and tool timeouts for browser work.
	Requires Node.js 24+ and an existing Codex login. Local mode requires Chrome; to use Browserbase instead, export `BROWSERBASE_API_KEY` before starting Codex. The plugin passes browser configuration through `env_vars`, so credentials stay out of its manifest. It sets longer startup and tool timeouts for browser work.

[cubic-dev-ai]

1 issue found across 8 files

Confidence score: 5/5

• packages/docs/v4/integrations/codex.mdx uses passive voice in the release guidance, which mildly reduces clarity about who must publish the npm package; name Browserbase as the responsible actor.

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/docs/v4/integrations/codex.mdx">

<violation number="1" location="packages/docs/v4/integrations/codex.mdx:9">
P2: Custom agent: **Stagehand docs prose guide**

The new Note uses passive voice for the unavailable npm release: “Until it is published.” Name the responsible actor, such as “Until Browserbase publishes it, use the source example below.”</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Dev as Developer
    participant CLI as Codex CLI
    participant PluginMgr as Plugin Manager
    participant Registry as GitHub Marketplace (browserbase/stagehand)
    participant Plugin as Stagehand Codex Plugin
    participant MCP as @browserbasehq/stagehand-mcp (npx)
    participant Env as Environment Variables
    participant Browser as Chrome / Browserbase

    Note over Dev,Browser: NEW: Repository Marketplace Plugin Installation Flow

    Dev->>CLI: codex plugin marketplace add browserbase/stagehand
    CLI->>Registry: Fetch marketplace manifest (.agents/plugins/marketplace.json)
    Registry-->>CLI: Return marketplace definition
    CLI->>CLI: Register marketplace in Codex config

    Dev->>CLI: codex plugin add stagehand@browserbase-stagehand
    CLI->>PluginMgr: Install plugin from local path (plugins/stagehand)
    PluginMgr->>Plugin: Read plugin.json + .mcp.json
    PluginMgr->>Env: Capture env_vars allowlist (STAGEHAND_BROWSER, BROWSERBASE_API_KEY, etc.)
    PluginMgr->>CLI: Enable MCP server "stagehand" in Codex profile

    Note over CLI,MCP: CHANGED: MCP Server Launch (Plugin-Provided Config)

    Dev->>CLI: Start new Codex task / restart
    CLI->>MCP: Spawn "npx -y @browserbasehq/stagehand-mcp@0.1.0"

    alt Credentials exported in environment
        MCP->>Env: Read BROWSERBASE_API_KEY / PROJECT_ID / STAGEHAND_* vars
        Env-->>MCP: Provide values (no hardcoded keys in config)
    else Missing credentials
        MCP->>Env: Attempt local Chrome fallback
        Env-->>MCP: STAGEHAND_BROWSER=chrome (or error)
    end

    MCP->>MCP: Apply startup_timeout_sec=120, tool_timeout_sec=120
    MCP->>Browser: Launch persistent browser session (stdio MCP)
    Browser-->>MCP: Browser ready (page state persists across calls)

    Note over CLI,Browser: Tool Invocation Loop (run / snapshot / screenshot)

    Dev->>CLI: Ask Codex: "Open example.com, snapshot, report title"
    CLI->>MCP: MCP tool call (run / snapshot / screenshot)
    MCP->>Browser: Execute tool against live page
    Browser-->>MCP: Return result (DOM snapshot, screenshot, etc.)
    MCP-->>CLI: Tool result payload

    alt Plugin vs manual config both enabled
        Note over CLI,MCP: WARNING: Each server starts its own browser - do not enable both
    end

    CLI-->>Dev: Present answer with snapshot / screenshot evidence

    Note over Dev,CLI: Alt: Direct CLI (No Plugin) - CHANGED config.toml template
    Dev->>CLI: codex with config.toml (env_vars + timeouts)
    CLI->>MCP: Spawn local stdio-server.mjs with env_vars passthrough
    MCP->>Env: Read same allowlisted credentials
    MCP->>Browser: Launch separate browser instance (isolated from plugin)

Loading

<sub>Requires human review: Auto-approval blocked because this review re-detected 1 unresolved issue already reported by Cubic.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Custom agent: Stagehand docs prose guide

The new Note uses passive voice for the unavailable npm release: “Until it is published.” Name the responsible actor, such as “Until Browserbase publishes it, use the source example below.”

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/integrations/codex.mdx, line 9:

<comment>The new Note uses passive voice for the unavailable npm release: “Until it is published.” Name the responsible actor, such as “Until Browserbase publishes it, use the source example below.”</comment>

<file context>
@@ -3,20 +3,35 @@ title: "Codex"
 
 <Note>
-Stagehand ships this experimental integration from the repository rather than publishing it as a standalone adapter.
+The plugin requires the first `@browserbasehq/stagehand-mcp@0.1.0` npm release. Until it is published, use the source example below.
 </Note>
 
</file context>

Suggested change

	The plugin requires the first `@browserbasehq/stagehand-mcp@0.1.0` npm release. Until it is published, use the source example below.
	The plugin requires the first `@browserbasehq/stagehand-mcp@0.1.0` npm release. Until Browserbase publishes it, use the source example below.