Stagehand Extended

A fork of Browserbase's Stagehand with enhanced browser configuration capabilities.

Why This Fork?

This fork extends Stagehand to provide greater control over browser instance configuration, specifically allowing you to:

• Use custom Chrome/Chromium installations
• Specify custom user profile directories
• Maintain persistent browser state across sessions

Other changes:

• Improvements to the logging system (previously, logging was verbose despite adjusting verbosity and debugDom arguments)

Relationship with Upstream Stagehand

This project maintains a close relationship with the upstream Stagehand repository:

• We regularly sync with the upstream repository to incorporate new features and fixes
• Our changes are focused solely on browser configuration capabilities
• Version numbers follow upstream with an -extended suffix (e.g., 1.12.0-extended.1)

Version Compatibility

| Stagehand Version | Stagehand Extended Version | |------------------|---------------------------| | 1.12.0 | 1.12.0-extended.1 |

For Contributors

To contribute while maintaining upstream compatibility:

# Setup
git clone https://github.com/your-org/stagehand-extended.git
git remote add upstream https://github.com/browserbase/stagehand.git

# Stay up-to-date
git checkout main
git fetch upstream
git merge upstream/main
git checkout extended-main
git rebase main

Installation

npm install @your-org/stagehand-extended
# or
yarn add @your-org/stagehand-extended

Key Differences from Original Stagehand

// Original Stagehand - Uses default browser paths
const stagehand = new Stagehand({
  env: "LOCAL"
});

// Stagehand Extended - Supports custom browser configuration
const stagehand = new Stagehand({
  env: "LOCAL",
  browserConfig: {
    // Use a specific Chrome/Chromium installation
    executablePath: "/custom/path/to/chrome-canary",
    // Use a specific profile directory to maintain state
    userDataDir: "/custom/path/to/user-data-dir"
  }
});

Additional Configuration Options

| Option | Description | Example | |--------|-------------|---------| | browserConfig.executablePath | Path to Chrome/Chromium executable | /Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary | | browserConfig.userDataDir | Path to browser user data directory | ~/Library/Application Support/Google/Chrome Canary |

Use Cases

1. Custom Browser Installations: Use specific Chrome/Chromium versions or installations
2. Profile Persistence: Maintain login states, cookies, and browser history
3. Cross-Platform Support: Specify paths appropriate for your operating system
4. Development Environments: Use different profiles for different environments

Example Configuration

import { Stagehand } from '@your-org/stagehand-extended';

// Using environment-specific paths
const stagehand = new Stagehand({
  env: "LOCAL",
  browserConfig: {
    executablePath: process.env.CHROME_PATH,
    userDataDir: process.env.CHROME_PROFILE_DIR
  }
});

// Using OS-specific paths
const stagehand = new Stagehand({
  env: "LOCAL",
  browserConfig: {
    executablePath: process.platform === 'darwin' 
      ? '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary'
      : 'C:\\Users\\YourUser\\AppData\\Local\\Google\\Chrome\\Application\\chrome.exe',
    userDataDir: process.platform === 'darwin'
      ? '~/Library/Application Support/Google/Chrome Canary'
      : 'C:\\Users\\YourUser\\AppData\\Local\\Google\\Chrome\\User Data'
  }
});

Stagehand is the easiest way to build browser automations. It is fully compatible with Playwright, offering three simple AI APIs (act, extract, and observe) on top of the base Playwright Page class that provide the building blocks for web automation via natural language.

Here's a sample of what you can do with Stagehand:

// Keep your existing Playwright code unchanged
await page.goto("https://docs.stagehand.dev");

// Stagehand AI: Act on the page
await page.act("click on the 'Quickstart'");

// Stagehand AI: Extract data from the page
const { description } = await page.extract({
  instruction: "extract the description of the page",
  schema: z.object({
    description: z.string(),
  }),
});

Why?

Stagehand adds determinism to otherwise unpredictable agents.

While there's no limit to what you could instruct Stagehand to do, our primitives allow you to control how much you want to leave to an AI. It works best when your code is a sequence of atomic actions. Instead of writing a single script for a single website, Stagehand allows you to write durable, self-healing, and repeatable web automation workflows that actually work.

[!NOTE] Stagehand is currently available as an early release, and we're actively seeking feedback from the community. Please join our Slack community to stay updated on the latest developments and provide feedback.

Documentation

Visit docs.stagehand.dev to view the full documentation.

Getting Started

Quickstart

To create a new Stagehand project configured to our default settings, run:

npx create-browser-app --example quickstart

Read our Quickstart Guide in the docs for more information.

You can also add Stagehand to an existing Typescript project by running:

npm install @browserbasehq/stagehand zod
npx playwright install # if running locally

Build and Run from Source

git clone https://github.com/browserbase/stagehand.git
cd stagehand
npm install
npx playwright install
npm run build
npm run example # run the blank script at ./examples/example.ts

Stagehand is best when you have an API key for an LLM provider and Browserbase credentials. To add these to your project, run:

cp .env.example .env
nano .env # Edit the .env file to add API keys

Contributing

[!NOTE]
We highly value contributions to Stagehand! For questions or support, please join our Slack community.

At a high level, we're focused on improving reliability, speed, and cost in that order of priority. If you're interested in contributing, we strongly recommend reaching out to Anirudh Kamath or Paul Klein in our Slack community before starting to ensure that your contribution aligns with our goals.

For more information, please see our Contributing Guide.

Acknowledgements

This project heavily relies on Playwright as a resilient backbone to automate the web. It also would not be possible without the awesome techniques and discoveries made by tarsier, and fuji-web.

We'd like to thank the following people for their contributions to Stagehand:

• Jeremy Press wrote the original MVP of Stagehand and continues to be an ally to the project.
• Navid Pour is heavily responsible for the current architecture of Stagehand and the act API.
• Sean McGuire is a major contributor to the project and has been a great help with improving the extract API and getting evals to a high level.
• Filip Michalsky has been doing a lot of work on building out integrations like Langchain and Claude MCP, generally improving the repository, and unblocking users.
• Sameel Arif is a major contributor to the project, especially around improving the developer experience.

License

Licensed under the MIT License.

Copyright 2025 Browserbase, Inc.