browserbase · pirate · Jan 22, 2026 · Jan 22, 2026 · Jan 22, 2026
diff --git a/.env.example b/.env.example
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -20,7 +20,7 @@ jobs:
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
@@ -36,7 +36,7 @@ jobs:
     runs-on: ${{ github.repository == 'stainless-sdks/stagehand-ruby' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:

diff --git a/.github/workflows/publish-gem.yml b/.github/workflows/publish-gem.yml
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:

diff --git a/.github/workflows/release-doctor.yml b/.github/workflows/release-doctor.yml
@@ -12,7 +12,7 @@ jobs:
     if: github.repository == 'browserbase/stagehand-ruby' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-please') || github.head_ref == 'next')
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Check release environment
         run: |

diff --git a/.gitignore b/.gitignore
@@ -4,7 +4,6 @@
 .prism.log
 .ruby-lsp/
 .yardoc/
-.env
 bin/tapioca
 Brewfile.lock.json
 doc/

diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "3.0.1"
+  ".": "3.0.2"
 }
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
-configured_endpoints: 7
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-2c6c017cc9ca1fcfe7b3902edfa64fb0420bdb46b1740c7c862e81e2132d4f7c.yml
-openapi_spec_hash: 220daf7e8f5897909a6c10e3385386e3
-config_hash: 1f709f8775e13029dc60064ef3a94355
+configured_endpoints: 8
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase%2Fstagehand-089c8670f1d7c2e9fa8e5c97010db7c24b8f162eb7cfe76ffa41d70fa46efe2f.yml
+openapi_spec_hash: 7a226aee8f3f2ab16febbe6bb35e1657
+config_hash: 8e4ed6629c178aa0c8aaf575cb07c544
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,13 @@
 # Changelog
 
+## 3.0.2 (2026-01-22)
+
+Full Changelog: [v3.0.1...v3.0.2](https://github.com/browserbase/stagehand-ruby/compare/v3.0.1...v3.0.2)
+
+### Chores
+
+* remove custom code ([3943364](https://github.com/browserbase/stagehand-ruby/commit/394336419ed210704639af03445858f44f03ba13))
+
 ## 3.0.1 (2026-01-15)
 
 Full Changelog: [v0.6.2...v3.0.1](https://github.com/browserbase/stagehand-ruby/compare/v0.6.2...v3.0.1)

diff --git a/Gemfile.lock b/Gemfile.lock
@@ -11,7 +11,8 @@ GIT
 PATH
   remote: .
   specs:
-    stagehand (3.0.1)
+    stagehand (3.0.2)
+      cgi
       connection_pool
 
 GEM
@@ -42,6 +43,7 @@ GEM
     base64 (0.3.0)
     benchmark (0.5.0)
     bigdecimal (3.3.1)
+    cgi (0.5.1)
     concurrent-ruby (1.3.5)
     connection_pool (2.5.4)
     console (1.34.2)

diff --git a/LICENSE b/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025 Stagehand
+   Copyright 2026 Stagehand
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

diff --git a/README.md b/README.md
@@ -1,67 +1,23 @@
-<div id="toc" align="center" style="margin-bottom: 0;">
-  <ul style="list-style: none; margin: 0; padding: 0;">
-    <a href="https://stagehand.dev">
-      <picture>
-        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/browserbase/stagehand/main/media/dark_logo.png" />
-        <img alt="Stagehand" src="https://raw.githubusercontent.com/browserbase/stagehand/main/media/light_logo.png" width="200" style="margin-right: 30px;" />
-      </picture>
-    </a>
-  </ul>
-</div>
-<p align="center">
-  <strong>The AI Browser Automation Framework</strong><br>
-  <a href="https://docs.stagehand.dev/v3/sdk/ruby">Read the Docs</a>
-</p>
-
-<p align="center">
-  <a href="https://github.com/browserbase/stagehand/tree/main?tab=MIT-1-ov-file#MIT-1-ov-file">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/browserbase/stagehand/main/media/dark_license.svg" />
-      <img alt="MIT License" src="https://raw.githubusercontent.com/browserbase/stagehand/main/media/light_license.svg" />
-    </picture>
-  </a>
-  <a href="https://stagehand.dev/discord">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/browserbase/stagehand/main/media/dark_discord.svg" />
-      <img alt="Discord Community" src="https://raw.githubusercontent.com/browserbase/stagehand/main/media/light_discord.svg" />
-    </picture>
-  </a>
-</p>
-
-<p align="center">
-	<a href="https://trendshift.io/repositories/12122" target="_blank"><img src="https://trendshift.io/api/badge/repositories/12122" alt="browserbase%2Fstagehand | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
-</p>
-
-<p align="center">
-If you're looking for other languages, you can find them
-<a href="https://docs.stagehand.dev/v3/first-steps/introduction"> here</a>
-</p>
-
-<div align="center" style="display: flex; align-items: center; justify-content: center; gap: 4px; margin-bottom: 0;">
-  <b>Vibe code</b>
-  <span style="font-size: 1.05em;"> Stagehand with </span>
-  <a href="https://director.ai" style="display: flex; align-items: center;">
-    <span>Director</span>
-  </a>
-  <span> </span>
-  <picture>
-    <img alt="Director" src="https://raw.githubusercontent.com/browserbase/stagehand/main/media/director_icon.svg" width="25" />
-  </picture>
-</div>
-
-## What is Stagehand?
-
-Stagehand is a browser automation framework used to control web browsers with natural language and code. By combining the power of AI with the precision of code, Stagehand makes web automation flexible, maintainable, and actually reliable.
-
-## Why Stagehand?
-
-Most existing browser automation tools either require you to write low-level code in a framework like Selenium, Playwright, or Puppeteer, or use high-level agents that can be unpredictable in production. By letting developers choose what to write in code vs. natural language (and bridging the gap between the two) Stagehand is the natural choice for browser automations in production.
-
-1. **Choose when to write code vs. natural language**: use AI when you want to navigate unfamiliar pages, and use code when you know exactly what you want to do.
-
-2. **Go from AI-driven to repeatable workflows**: Stagehand lets you preview AI actions before running them, and also helps you easily cache repeatable actions to save time and tokens.
-
-3. **Write once, run forever**: Stagehand's auto-caching combined with self-healing remembers previous actions, runs without LLM inference, and knows when to involve AI whenever the website changes and your automation breaks.
+# Stagehand Ruby API library
+
+The Stagehand Ruby library provides convenient access to the Stagehand REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/browserbase/stagehand-ruby#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
+
+It is generated with [Stainless](https://www.stainless.com/).
+
+## MCP Server
+
+Use the Stagehand MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=stagehand-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInN0YWdlaGFuZC1tY3AiXX0)
+[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22stagehand-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22stagehand-mcp%22%5D%7D)
+
+> Note: You may need to set environment variables in your MCP client.
+
+## Documentation
+
+Documentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/stagehand).
+
+The REST API documentation can be found on [docs.stagehand.dev](https://docs.stagehand.dev).
 
 ## Installation
 
@@ -70,7 +26,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "stagehand", "~> 3.0.1"
+gem "stagehand", "~> 3.0.2"
 ```
 
 <!-- x-release-please-end -->
@@ -81,115 +37,15 @@ gem "stagehand", "~> 3.0.1"
 require "bundler/setup"
 require "stagehand"
 
-# Create a new Stagehand client with your credentials
-client = Stagehand::Client.new(
-  browserbase_api_key: ENV["BROWSERBASE_API_KEY"],      # defaults to ENV["BROWSERBASE_API_KEY"]
-  browserbase_project_id: ENV["BROWSERBASE_PROJECT_ID"], # defaults to ENV["BROWSERBASE_PROJECT_ID"]
-  model_api_key: ENV["MODEL_API_KEY"]                   # defaults to ENV["MODEL_API_KEY"]
-)
-
-# Start a new browser session
-start_response = client.sessions.start(
-  model_name: "openai/gpt-5-nano"
-)
-puts "Session started: #{start_response.data.session_id}"
-
-session_id = start_response.data.session_id
-
-# Navigate to a webpage
-client.sessions.navigate(
-  session_id,
-  url: "https://news.ycombinator.com"
-)
-puts "Navigated to Hacker News"
-
-# Use Observe to find possible actions on the page
-observe_response = client.sessions.observe(
-  session_id,
-  instruction: "find the link to view comments for the top post"
-)
-
-actions = observe_response.data.result
-puts "Found #{actions.length} possible actions"
-
-# Take the first action returned by Observe
-action = actions.first
-puts "Acting on: #{action.description}"
-
-# Pass the structured action to Act
-# Convert the observe result to a hash and ensure method is set to "click"
-act_response = client.sessions.act(
-  session_id,
-  input: action.to_h.merge(method: "click")
-)
-puts "Act completed: #{act_response.data.result[:message]}"
-
-# Extract data from the page
-# We're now on the comments page, so extract the top comment text
-extract_response = client.sessions.extract(
-  session_id,
-  instruction: "extract the text of the top comment on this page",
-  schema: {
-    type: "object",
-    properties: {
-      comment_text: {
-        type: "string",
-        description: "The text content of the top comment"
-      },
-      author: {
-        type: "string",
-        description: "The username of the comment author"
-      }
-    },
-    required: ["comment_text"]
-  }
-)
-puts "Extracted data: #{extract_response.data.result}"
-
-# Get the author from the extracted data
-extracted_data = extract_response.data.result
-author = extracted_data[:author]
-puts "Looking up profile for author: #{author}"
-
-# Use the Agent to find the author's profile
-# Execute runs an autonomous agent that can navigate and interact with pages
-execute_response = client.sessions.execute(
-  session_id,
-  execute_options: {
-    instruction: "Find any personal website, GitHub, LinkedIn, or other best profile URL for the Hacker News user '#{author}'. " \
-                 "Click on their username to go to their profile page and look for any links they have shared.",
-    max_steps: 15
-  },
-  agent_config: {
-    model: Stagehand::ModelConfig::ModelConfigObject.new(
-      model_name: "openai/gpt-5-nano",
-      api_key: ENV["MODEL_API_KEY"]
-    ),
-    cua: false
-  }
+stagehand = Stagehand::Client.new(
+  browserbase_api_key: ENV["BROWSERBASE_API_KEY"], # This is the default and can be omitted
+  browserbase_project_id: ENV["BROWSERBASE_PROJECT_ID"], # This is the default and can be omitted
+  model_api_key: ENV["MODEL_API_KEY"] # This is the default and can be omitted
 )
-puts "Agent completed: #{execute_response.data.result[:message]}"
-puts "Agent success: #{execute_response.data.result[:success]}"
-puts "Agent actions taken: #{execute_response.data.result[:actions]&.length || 0}"
-
-# End the session to cleanup browser resources
-client.sessions.end_(session_id)
-puts "Session ended"
-```
-
-### Running the Example
-
-Set the required environment variables and run the example script:
 
-```bash
-# Set your credentials
-export BROWSERBASE_API_KEY="your-browserbase-api-key"
-export BROWSERBASE_PROJECT_ID="your-browserbase-project-id"
-export MODEL_API_KEY="your-openai-api-key"
+response = stagehand.sessions.act("00000000-your-session-id-000000000000", input: "click the first link on the page")
 
-# Install dependencies and run
-bundle install
-bundle exec ruby examples/basic.rb
+puts(response.data)
 ```
 
 ### Streaming
@@ -367,25 +223,25 @@ stagehand.sessions.act("00000000-your-session-id-000000000000", **params)
 Since this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:
 
 ```ruby
-# :typescript
-puts(Stagehand::SessionActParams::XLanguage::TYPESCRIPT)
+# :true
+puts(Stagehand::SessionActParams::XStreamResponse::TRUE)
 
-# Revealed type: `T.all(Stagehand::SessionActParams::XLanguage, Symbol)`
-T.reveal_type(Stagehand::SessionActParams::XLanguage::TYPESCRIPT)
+# Revealed type: `T.all(Stagehand::SessionActParams::XStreamResponse, Symbol)`
+T.reveal_type(Stagehand::SessionActParams::XStreamResponse::TRUE)
 ```
 
 Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
 
 ```ruby
 # Using the enum constants preserves the tagged type information:
 stagehand.sessions.act(
-  x_language: Stagehand::SessionActParams::XLanguage::TYPESCRIPT,
+  x_stream_response: Stagehand::SessionActParams::XStreamResponse::TRUE,
   # …
 )
 
 # Literal values are also permissible:
 stagehand.sessions.act(
-  x_language: :typescript,
+  x_stream_response: :true,
   # …
 )
 ```