hyper-agent-browser (hab)

Pure Browser Automation CLI for AI Agents

📖 中文文档 (Chinese Documentation)

✨ Features

• 🎯 @eN Element References - No manual selectors needed, auto-generates @e1, @e2 references
• 🔐 Session Persistence - Maintains login state, supports multi-account isolation
• 🎭 Anti-Detection - Built on Patchright, bypasses automation detection
• ⚡ Fast Startup - Bun runtime, cold start ~25ms
• 🤖 AI Agent Friendly - Designed for Claude Code and other AI agents
• 🔒 Security Hardened - Sandbox isolation, permission control, session protection
• 📊 Data Extraction - Auto-extract tables/lists/forms/metadata
• 🌐 Network Monitoring - Intercept XHR/Fetch requests, get API data directly
• ⏳ Smart Waiting - Network idle + DOM stable dual strategy

🚀 Quick Start

Installation

Using npm (Recommended)

# Global install
npm install -g hyper-agent-browser

# Or use Bun
bun install -g hyper-agent-browser

# Or use npx (no install needed)
npx hyper-agent-browser --version

From Source

git clone https://github.com/anthropics/hyper-agent-browser.git
cd hyper-agent-browser
bun install
bun run build  # Build binary to dist/hab

Download Pre-built Binary

Visit GitHub Releases to download binaries for your platform.

Basic Usage

# 1. Open a webpage (headed mode to see browser)
hab --headed open https://google.com

# 2. Get interactive elements snapshot
hab snapshot -i

# Output example:
# URL: https://google.com
# Title: Google
#
# Interactive Elements:
# @e1  [textbox]   "Search" (focused)
# @e2  [button]    "Google Search"
# @e3  [button]    "I'm Feeling Lucky"
# @e4  [link]      "Gmail"
# @e5  [link]      "Images"

# 3. Use @eN references to interact
hab fill @e1 "Bun JavaScript runtime"
hab press Enter

# 4. Wait for page load
hab wait 2000

# 5. Take screenshot
hab screenshot -o result.png

Session Management (Multi-Account Isolation)

# Personal Gmail account
hab -s personal-gmail open https://mail.google.com
hab -s personal-gmail snapshot -i

# Work Gmail account
hab -s work-gmail open https://mail.google.com
hab -s work-gmail snapshot -i

# List all sessions
hab sessions

# Close specific session
hab close -s personal-gmail

Data Extraction

# Extract table data
hab open https://example.com/users
hab extract-table > users.json

# Extract list data (auto-detect product/article lists)
hab extract-list --selector ".product-list" > products.json

# Extract form state
hab extract-form > form_data.json

# Extract page metadata (SEO/OG/Schema.org)
hab extract-meta --include seo,og > metadata.json

Network Monitoring

# Start network listener
LISTENER_ID=$(hab network-start --filter xhr,fetch --url-pattern "*/api/*" | jq -r '.listenerId')

# Perform actions (pagination/clicks)
hab click @e5
hab wait-idle

# Stop listener and get all API data
hab network-stop $LISTENER_ID > api_data.json

Smart Waiting

# Wait for page fully idle (network + DOM)
hab wait-idle --timeout 30000

# Wait for element visible
hab wait-element "css=.data-row" --state visible

# Wait for loading animation to disappear
hab wait-element "css=.loading" --state detached

📖 Command Reference

Navigation Commands

| Command | Description | Example | |---------|-------------|---------| | open <url> | Open webpage | hab open https://example.com | | reload | Refresh current page | hab reload | | back | Go back | hab back | | forward | Go forward | hab forward |

Action Commands

| Command | Description | Example | |---------|-------------|---------| | click <selector> | Click element | hab click @e1 | | fill <selector> <value> | Fill input field | hab fill @e1 "hello" | | type <text> | Type text character by character | hab type "password" | | press <key> | Press key | hab press Enter | | scroll <direction> [amount] | Scroll page | hab scroll down 500 | | hover <selector> | Hover over element | hab hover @e3 | | select <selector> <value> | Select dropdown option | hab select @e2 "Option 1" | | wait <ms\|condition> | Wait for time or condition | hab wait 3000 |

Info Commands

| Command | Description | Example | |---------|-------------|---------| | snapshot [-i\|--interactive] | Get page snapshot | hab snapshot -i | | screenshot [-o <file>] [--full-page] | Take screenshot | hab screenshot -o page.png | | url | Get current URL | hab url | | title | Get page title | hab title | | evaluate <script> | Execute JavaScript | hab evaluate "document.title" |

Session Commands

| Command | Description | Example | |---------|-------------|---------| | sessions | List all sessions | hab sessions | | close [-s <name>] | Close session | hab close -s gmail |

Global Options

| Option | Description | Default | |--------|-------------|---------| | -s, --session <name> | Session name | default | | --headed | Headed mode (show browser) | false | | --channel <chrome\|msedge> | Browser type | chrome | | --timeout <ms> | Timeout | 30000 |

🤖 AI Agent Integration (Claude Code)

hyper-agent-browser is designed for AI agents and integrates seamlessly with Claude Code.

Install Skill File

# Method 1: Copy from local repo
mkdir -p ~/.claude/skills/hyper-agent-browser
cp skills/hyper-agent-browser.md ~/.claude/skills/hyper-agent-browser/skill.md

# Method 2: Direct download
mkdir -p ~/.claude/skills/hyper-agent-browser
curl -o ~/.claude/skills/hyper-agent-browser/skill.md \
  https://raw.githubusercontent.com/anthropics/hyper-agent-browser/main/skills/hyper-agent-browser.md

Usage Examples

After installing the skill, Claude Code will automatically recognize and use hab commands:

"Help me open Google, search for 'Bun runtime' and take a screenshot"
"Log into my Gmail account and find the number of unread emails"
"Visit Twitter and get all tweet titles from the homepage"

Claude will automatically:

1. Use hab open to open the webpage
2. Use hab snapshot -i to get element references
3. Analyze the snapshot to find target elements (e.g., @e5)
4. Use hab click @e5 and other commands to complete the task

📋 Selector Format

| Format | Example | Description | Recommended | |--------|---------|-------------|-------------| | @eN | @e1, @e5 | Element reference (from snapshot) | ⭐⭐⭐⭐⭐ | | css= | css=#login | CSS selector | ⭐⭐⭐ | | text= | text=Sign in | Text match | ⭐⭐⭐⭐ | | xpath= | xpath=//button | XPath selector | ⭐⭐ |

Recommended: Use @eN references:

• No manual selector writing
• Auto-handles dynamic IDs/Classes
• AI Agent friendly

🔒 Security Features

• ✅ evaluate Sandbox - Whitelist mode, blocks dangerous operations
• ✅ Session File Protection - Permissions set to 0o600
• ✅ Chrome Extension Verification - Whitelist + dangerous permission filtering
• ✅ System Keychain Isolation - Isolated password storage by default
• ✅ Config Key Whitelist - Prevents dangerous browser argument injection

🏗️ Architecture

src/
├── cli.ts              # CLI entry (Commander.js)
├── browser/
│   └── manager.ts      # Browser lifecycle management
├── daemon/
│   ├── server.ts       # Daemon server
│   ├── client.ts       # Daemon client
│   └── browser-pool.ts # Browser instance pool
├── session/
│   ├── manager.ts      # Session management
│   └── store.ts        # UserData persistence
├── commands/
│   ├── navigation.ts   # open/reload/back/forward
│   ├── actions.ts      # click/fill/type/press/scroll
│   ├── info.ts         # snapshot/screenshot/evaluate
│   ├── extract.ts      # Data extraction commands
│   └── network.ts      # Network monitoring
├── snapshot/
│   ├── accessibility.ts    # Extract from Accessibility Tree
│   ├── dom-extractor.ts    # DOM extractor (fallback)
│   └── reference-store.ts  # @eN mapping storage
└── utils/
    ├── selector.ts     # Selector parsing
    ├── config.ts       # Config management
    └── errors.ts       # Error handling

📊 Tech Stack

• Bun 1.2.21 - JavaScript runtime
• Patchright 1.57.0 - Anti-detection Playwright fork
• Commander.js 12.1.0 - CLI framework
• Zod 3.25.76 - Data validation
• Biome 1.9.4 - Code linting

🛠️ Development

# Clone repo
git clone https://github.com/anthropics/hyper-agent-browser.git
cd hyper-agent-browser

# Install dependencies
bun install

# Development mode
bun dev -- --headed open https://google.com

# Run tests
bun test

# Type check
bun run typecheck

# Lint
bun run lint

# Build
bun run build       # Current platform
bun run build:all   # All platforms

📚 Documentation

• Quick Start Guide
• Element Reference Guide
• Google Profile Integration
• Developer Docs
• Technical Spec
• Skill Documentation
• 中文文档 (Chinese)

🤝 Contributing

Pull Requests welcome! Please ensure:

• ✅ TypeScript type check passes: bun run typecheck
• ✅ Tests pass: bun test
• ✅ Lint passes: bun run lint

📄 License

MIT

🔗 Links

• npm: https://www.npmjs.com/package/hyper-agent-browser
• GitHub: https://github.com/anthropics/hyper-agent-browser
• Issues: https://github.com/anthropics/hyper-agent-browser/issues
• Releases: https://github.com/anthropics/hyper-agent-browser/releases

🙏 Acknowledgments

• Patchright - Anti-detection Playwright fork
• Bun - Fast JavaScript runtime
• Claude Code - AI programming assistant

Made with ❤️ for AI Agents