Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/l-xiaoshen/handstage/llms.txt

Use this file to discover all available pages before exploring further.

Handstage is a TypeScript SDK for automating Chrome via the Chrome DevTools Protocol (CDP). Instead of wrapping another automation library, Handstage speaks CDP directly — giving you precise, low-latency control over the browser with a clean, fully-typed API and no hidden abstractions.

​
Packages

Handstage ships as three focused packages:

@handstage/core

The main package. Provides the V3 class for launching and connecting to Chrome, plus V3Context, Page, and Locator for navigating and interacting with pages.

@handstage/agent

AI tooling built on @handstage/core. Exposes fully-typed browser tools you can pass directly to any LLM via the Vercel AI SDK.

@handstage/dom

Internal DOM utilities used by @handstage/core. Not intended for direct use in application code.

​
Key features

Direct CDP control

Every browser action goes through Chrome’s DevTools Protocol — no Playwright, no Puppeteer, no intermediate runtime.

Typed API

The entire public surface is written in TypeScript with strict types. Autocomplete works everywhere, and mistakes are caught at compile time.

Isolated browser contexts

Create independent browser contexts — each with its own cookies, storage, and tabs — from a single Chrome instance.

Flexible connection modes

Launch a fresh Chrome process, attach to one already running via CDP URL, or bring your own CDP transport or session.

Accessibility-first targeting

Capture structured accessibility trees for reliable element targeting, useful for both test automation and AI agent vision.

AI agent integration

@handstage/agent wraps core browser actions as AI tool definitions, making it straightforward to give an LLM browser control.

​
Architecture overview

Handstage is organized around a four-level hierarchy:
  • V3 — the entry point. Call V3.connectLocal() to launch or attach to Chrome. Owns the CDP connection and exposes a default browser context.
  • V3Context — a browser context (like a profile or incognito window). Holds cookies, local storage, and a set of pages. Access the default one via browser.context, or create an isolated one with browser.create().
  • Page — a single browser tab. Use context.newPage(url) to open one. Provides navigation, screenshot, and locator methods.
  • Locator — a handle to one or more elements matching a CSS or XPath selector. Use page.locator(selector) to get one, then call .click(), .fill(), .type(), .hover(), and more.

​
Next steps

Quickstart

Launch Chrome and automate your first page in minutes.

API reference

Full reference for V3, V3Context, Page, and Locator.

Build docs developers (and LLMs) love

Get started for freeTalk to us