Why we’re graduating from Playwright

Copy linkPlaywright got us here - where we’re going next

Stagehand began as an AI-centric layer built on Playwright, adding new capabilities like act, extract, and observe on top of its existing API. That choice lets developers plug Stagehand into existing scripts in minutes and ship real automations fast. As the community has grown and our ambitions are expanding, we have run into the natural limits of building on a test‑first framework. This post is a look back at why Playwright was the right starting point, and why we’re taking Stagehand deeper into the browser stack.

Copy linkWhy we started on Playwright

In the early days, our goals were clear: remove friction, meet developers where they are, and earn trust. Returning a Stagehand‑enhanced Page / Context meant your Playwright code kept working, now with AI‑powered primitives on the same object.

Result: minimal migration, lots of adoption, and a fast feedback loop with real users. The docs still say it best: “Full Playwright compatibility… use any Playwright API alongside Stagehand.”

That compatibility made Stagehand a great and pragmatic choice for teams taking their first steps into AI‑assisted automation with us.

Copy linkWhat changed as we scaled

As Stagehand and our community have grown, we’ve noticed a few seams showing. Less about quality and more about fit.

Copy link1) Testing DNA vs. automation throughput

Playwright’s actionability checks and auto‑waiting are fantastic for end‑to‑end tests: click only when an element is visible, stable, enabled, and receiving events. For automation, where we often want to move quickly and accept more direct control, those checks can add latency and complexity we don’t always need.

Copy link2) We need CDP‑level control (especially for frames)

Stagehand builds rich, structured context for models by reading directly from the Chrome DevTools Protocol (CDP): accessibility trees, DOM snapshots, network events, and more. Doing that well requires stable identifiers and precise scoping. This is where we hit friction:

• Frame identity & scoping. Playwright doesn’t expose a unique frame ID, which makes lifecycle tracking and per‑frame CDP routing harder than it needs to be.
• Practical interop gaps. As Sean wrote in our iframes update, Playwright and CDP don’t always play perfectly together when you need to target CDP to specific frames and stitch multi‑frame state back together. We worked around this with a unified tree, deep XPath locators, and smarter session mapping, but this was all work we had to do because of those gaps.
• Per‑page CDP sessions. Playwright exposes CDP via CDPSession, typically scoped from a page/context. That’s useful, but once you’re doing heavy CDP‑first work, you want finer‑grained control and fewer round‑trips.

In short: when a product is automation (not testing), we eventually want to operate at the protocol layer without extra hurdles.

Copy link3) Operational headroom matters

Our users have reported memory growth in long‑running sessions and version‑specific regressions. Even when issues are addressed upstream, staying strictly on the Playwright rails can make it harder for us to choose different tradeoffs for long‑lived automation workloads.

Copy linkWhat we learned building on top of Playwright

• It was the fastest on‑ramp. Developers could drop Stagehand into existing code and get value right away.
• The surface area is huge. A testing‑first framework brings a long tail of APIs and behaviors we don’t lean on, and maintaining perfect fidelity to that surface area constrains how fast we can ship automation‑first features.
• Frames are the real world. Modern sites are a thicket of same‑origin and out‑of‑process iframes. Doing great work there means embracing CDP deeply and minimizing requests sent over the websocket (Our iframes post walks through the details).

Copy linkPrinciples guiding the next phase

We’re codifying a few principles that reflect what our users actually need:

1. Automation‑first semantics. Keep the ergonomics developers love, but put throughput and control ahead of test ergonomics (you can still opt‑in to waiting and safety rails when you need them!).
2. CDP‑native performance. Expose the right hooks so Stagehand can build context efficiently (fewer, smarter messages), especially across iframes, workers, and tabs.
3. A smaller core, fewer surprises. Focus on the primitives that matter for automation without absorbing unrelated testing machinery.
4. Compatibility where it counts. Developers shouldn’t have to rewrite everything to benefit from these changes. The spirit of “drop‑in and go” stays.

Playwright has been a terrific foundation: a clean mental model, a mature ecosystem, and an incredible community. It has helped Stagehand hit the ground running and reach far more developers, far more quickly, than we could have alone. As we keep pushing what’s possible in browser automation, we’re taking the lessons (and the gratitude) with us.

Stagehand’s mission hasn’t changed: give developers and models a browser they can trust. The work ahead is about sharpening that promise: making the core smaller, the behavior more predictable, and the performance feel native to the metal.

More soon. :)

Build automations with StagehandGet started