@browserbasehq/stagehand

An AI web browsing framework focused on simplicity and extensibility.
Read the Docs

---

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. It also makes Playwright more accessible to non-technical users and less vulnerable to minor changes in the UI/DOM.

Anything that can be done in a browser can be done with Stagehand. Consider:

1. Go to Hacker News and extract the top stories of the day
2. Log into Amazon, search for AirPods, and buy the most relevant product
3. Go to ESPN, search for Steph Curry, and get stats for his last 10 games

Stagehand makes it easier to write durable, performant browser automation code. When used with Browserbase, it offers unparalleled debugging tools like session replay and step-by-step debugging.

[!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 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.

Changelog

1.9.0

Minor Changes

• #374 207244e Thanks @sameelarif! - Pass in a Stagehand Page object into the on("popup") listener to allow for multi-page handling.

• #367 75c0e20 Thanks @kamath! - Logger in LLMClient is inherited by default from Stagehand. Named rather than positional arguments are used in implemented LLMClients.

• #381 db2ef59 Thanks @kamath! - make logs only sync

• #385 5899ec2 Thanks @sameelarif! - Moved the LLMClient logger paremeter to the createChatCompletion method options.

• #364 08907eb Thanks @kamath! - exposed llmClient in stagehand constructor

Patch Changes

• #383 a77efcc Thanks @sameelarif! - Unified LLM input/output types for reduced dependence on OpenAI types

• b7b3701 Thanks @kamath! - Fix $1-types exposed to the user

• #353 5c6f14b Thanks @kamath! - Throw custom error if context is referenced without initialization, remove act/extract handler from index

• #360 89841fc Thanks @kamath! - Remove stagehand nav entirely

• #379 b1c6579 Thanks @seanmcguire12! - dont require LLM Client to use non-ai stagehand functions

• #371 30e7d09 Thanks @kamath! - pretty readme :)

• #382 a41271b Thanks @sameelarif! - Added example implementation of the Vercel AI SDK as an LLMClient

• #344 c1cf345 Thanks @kamath! - Remove duplicate logging and expose Page/BrowserContext types