Skip to content

CLAUDE.md

Latest commit

 

History

History
84 lines (60 loc) · 3.47 KB

CLAUDE.md

File metadata and controls

84 lines (60 loc) · 3.47 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the Hyperbrowser Python SDK - a client library for interacting with the Hyperbrowser API for cloud browser automation. It provides both synchronous (Hyperbrowser) and asynchronous (AsyncHyperbrowser) clients.

Development Commands

Use Python 3.12 for the Poetry development environment. CI exercises runtime compatibility from Python 3.8 through 3.14.

# Install dependencies (uses Poetry)
poetry install

# Run linting with ruff
poetry run ruff check .

# Format code with ruff
poetry run ruff format .

# Run the non-E2E test suite
poetry run pytest tests --ignore=tests/sandbox/e2e

Architecture

Client Structure

The SDK follows a dual sync/async pattern with mirrored implementations:

  • Entry Points: Hyperbrowser (sync) and AsyncHyperbrowser (async) in hyperbrowser/__init__.py
  • Base Class: HyperbrowserBase in client/base.py handles common config and URL building
  • Transport Layer: transport/ contains SyncTransport and AsyncTransport wrapping httpx clients

Manager Pattern

Both clients expose identical APIs through manager classes that handle specific resource types:

client.sessions     # Browser session management
client.scrape       # Web scraping jobs
client.scrape.batch # Batch web scraping jobs
client.crawl        # Website crawling jobs
client.extract      # Data extraction jobs
client.web          # Web fetch/search operations
client.web.batch_fetch # Batch web fetch operations
client.agents       # AI agent integrations (browser_use, cua, claude_computer_use, hyper_agent, gemini_computer_use, grok_computer_use, jev_computer_use, meta_computer_use)
client.profiles     # Browser profile management
client.extensions   # Browser extension management
client.team         # Team/credit info
client.computer_action  # Low-level computer actions
client.secrets      # Encrypted secrets (secret, totp, op_token)
client.vaults       # Named sets of stored secrets

Each manager lives in client/managers/sync_manager/ or client/managers/async_manager/ with identical method signatures.

Request Types and Models

TypedDict request types are in hyperbrowser/types/. Pydantic response models and backwards-compatible request classes remain in hyperbrowser/models/. Managers accept either request dictionaries or the legacy request model and normalize both through the shared request serializer.

Response and legacy models are re-exported from hyperbrowser/models/__init__.py; request TypedDicts are re-exported from hyperbrowser/types/__init__.py.

Pre-built Tools

hyperbrowser/tools/ contains ready-to-use tool definitions for OpenAI, Anthropic and Gemini function calling:

  • WebsiteScrapeTool, WebsiteScreenshotTool, WebsiteCrawlTool, WebsiteExtractTool, BrowserUseTool, CredentialFillTool
  • Each has openai_tool_definition, anthropic_tool_definition, plus sync/async runnable methods
  • CredentialFillTool also has gemini_tool_definition; tools/gemini.py defines only credential fill

Key Patterns

  • API Key: Via constructor api_key= or HYPERBROWSER_API_KEY env var
  • Base URL: Defaults to https://api.hyperbrowser.ai, configurable via base_url= or HYPERBROWSER_BASE_URL
  • Job Polling: Managers provide start_and_wait() methods that poll until completion
  • Context Managers: AsyncHyperbrowser supports async with for automatic cleanup