Contribute to Stagehand
Best practices for making a meaningful contribution to Stagehand
Codeowners and Subject-Matter Experts
Stagehand repo codeowners are Anirudh Kamath and Paul Klein. Any contribution must be explicitly approved by a codeowner.
Stagehand subject-matter experts are as follows:
- Sean McGuire - general repo, but especially evals and
extract
- Navid Pour - general repo, but especially
act
- Sameel Arif - general repo
- Filip Michalsky - general repo and integrations like Langchain or Claude MCP
- Miguel Gonzalez - general repo and accessibility tree (a11y tree) implementation
Special thanks to Jeremy Press (the OG) and all the contributors for your help in making Stagehand the best browser automation framework.
Please do not hesitate to reach out to anyone listed here in the public Slack channel
Before you start
General Workflow
Get listed as one of our beloved contributors!
-
Discuss your proposed contribution before starting. Not doing this runs you the risk of entirely discarding something you put considerable time and effort into. You can DM Anirudh on Slack or book 30 minutes for a 1on1 call.
-
Open a Pull Request. Create a fork of this repository, and follow GitHub’s instructions to create a Pull Request. This allows our team to review your contribution and leave comments.
-
Wait for Review. We’ll do our best to get to your contribution as soon as possible. If it’s been 2-3 days and you have yet to receive any comments, DM Anirudh on Slack
-
Merge into
evals
branch. We don’t let external contributors run our CI via GitHub Actions to prevent spam and misuse. If your contribution passes an initial screen, we’ll run our evals on it- By default, all PRs run the following tests that you can also run from the repo source:
- Lint (
npm run lint
) - Runsprettier
andeslint
. If this fails, you can most likely runnpm run format
to fix some simple linting errors. - Build (
npm run build
) - Lints and builds TS → JS indist/
viatsup
- End-to-End (
npm run e2e
) - These are deterministic end-to-end Playwright tests to ensure the integrity of basic Playwright functionality ofstagehand.page
andstagehand.context
as well as compatibility with the Browserbase API - Combination (
npm run evals category combination
) - This runs AI-based end-to-end tests using combinations ofact
,extract
, andobserve
- Lint (
- If you’re changing anything about
act
,extract
, orobserve
itself, we might also run specific act/extract/observe evals to ensure existing functionality doesn’t significantly drop.
- By default, all PRs run the following tests that you can also run from the repo source:
-
Cleanup and merge to main. Once it’s in
evals
, unfortunately the original contributor can’t make any further changes. The internal Stagehand team will be responsible for cleaning up the code and bringing it into main.
Help make everyone’s lives easier
-
Use draft PRs. If your PR is a work in progress, please convert it to a draft (see below) while you’re working on it, and mark it for review/add reviewers when you’re ready. This helps us prevent clutter in the review queue.
-
Provide a reproducible test plan. Include an eval (preferred) or example. We can’t merge your PR if we can’t run anything that specifically highlights your contribution.
- Write a script in
evals/tasks
assomeTask.ts
- Add your script to
evals.config.json
with default categorycombination
(or act/extract/observe if you’re only testing act/extract/observe).
- Write a script in
-
Add a changeset. Run
npx changeset
to add a changeset that will directly reflect in theCHANGELOG
in the upcoming release.patch
- no net new functionality to an end-userminor
- some net new functionality to an end-user (new function parameter, new exposed type, etc.)major
- you shouldn’t be committing a major change