hyperbrowserai · shrisukhani · Sep 29, 2025
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,106 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+This is a collection of example projects demonstrating Hyperbrowser SDK usage. Each example is a standalone TypeScript project showing different use cases for web automation, scraping, and AI-powered workflows.
+
+## Key Architecture Patterns
+
+### SDK Integration
+All examples use the `@hyperbrowser/sdk` package as the core browser automation client. Common pattern:
+
+```typescript
+import { Hyperbrowser } from '@hyperbrowser/sdk';
+const hbClient = new Hyperbrowser({ apiKey: process.env.HYPERBROWSER_API_KEY });
+```
+
+### Example Structure
+Most examples follow this structure:
+- Single entry point TypeScript file (e.g., `example-name.ts`)
+- `package.json` with dependencies
+- README.md explaining the use case
+- Requires `HYPERBROWSER_API_KEY` environment variable
+- Many also require `OPENAI_API_KEY` for LLM features
+
+### Complex Multi-Module Examples
+Some examples have more sophisticated architectures:
+
+**hb-intern-bot** (`hb-intern-bot/src/`):
+- Pipeline architecture: scrape → normalize → score → summarize → output
+- Multiple scrapers (`scraper/`) for different sources (HN, Reddit, ProductHunt, blogs)
+- Event aggregation and scoring system
+- Watch mode for continuous monitoring
+
+**llm-crawl**:
+- CLI tool using `commander` for argument parsing
+- Combines Hyperbrowser Crawl API + OpenAI LLM processing
+- Supports multiple output formats (JSON, JSONL, FAISS database)
+- Example: `llmcrawl "instruction" --json -o output.jsonl`
+
+**site2prompt**:
+- Web content → prompt-ready format converter
+- Token budgeting and deduplication
+- Multiple output formats (JSONL, CSV, citations)
+- Heuristic and LLM-based compression modes
+
+## Common Development Commands
+
+### Running Examples
+Most examples are run with:
+```bash
+cd <example-directory>
+npm install
+npx tsx <main-file>.ts
+```
+
+Or (if configured in package.json):
+```bash
+npm run dev
+```
+
+### Building TypeScript Projects
+Examples with build scripts:
+```bash
+npm run build
+```
+
+### Environment Setup
+Required for all examples:
+```bash
+export HYPERBROWSER_API_KEY="your-key"
+```
+
+Many examples also need:
+```bash
+export OPENAI_API_KEY="your-key"
+```
+
+## Dependencies
+
+Common dependencies across examples:
+- `@hyperbrowser/sdk` - Core browser automation SDK
+- `@hyperbrowser/agent` - Agent-based automation (some examples)
+- `dotenv` - Environment variable management
+- `typescript` + `ts-node` or `tsx` - TypeScript execution
+- `openai` - OpenAI API client
+- `@langchain/openai` - LangChain integration (some examples)
+- `zod` - Schema validation (some examples)
+- `commander` / `yargs` - CLI frameworks (CLI-based examples)
+- `cheerio` - HTML parsing (scraping examples)
+
+## Important Notes
+
+- Each example is independent with its own `package.json`
+- No shared code between examples (intentionally isolated for clarity)
+- Examples demonstrate patterns, not production-ready code
+- The SDK version may vary between examples (check individual `package.json` files)
+- Some examples output to files, others to stdout
+- API keys should be in `.env` file or environment variables, never committed
+
+## Resources
+
+- Documentation: https://docs.hyperbrowser.ai
+- Discord: https://discord.gg/zsYzsgVRjh
+- Support: info@hyperbrowser.ai
diff --git a/CUA-CTA-Validator/README.md b/CUA-CTA-Validator/README.md
@@ -1,62 +1,160 @@
 # CUA-CTA-Validator
 
-A tool that uses Hyperbrowser's Conversational User Agent (OPENAI CUA) to validate and analyze Call-to-Action (CTA) buttons on websites.
+**Built with [Hyperbrowser](https://hyperbrowser.ai)**
 
-## Description
+An intelligent CLI tool that uses Hyperbrowser's Conversational User Agent (CUA) with OpenAI to automatically validate and analyze Call-to-Action (CTA) buttons on websites. Perfect for UX audits, accessibility checks, and conversion optimization workflows.
 
-This tool automatically identifies the main CTA button in a website's hero section and performs a comprehensive analysis of its accessibility and SEO characteristics. It then provides specific improvement suggestions based on this analysis.
+## ✨ Features
 
-## Features
+- 🔍 **Smart CTA Detection**: Automatically identifies the primary CTA button in hero sections
+- ♿ **Accessibility Analysis**: Evaluates color contrast, text clarity, and ARIA attributes
+- 📊 **SEO Best Practices**: Checks positioning, semantic markup, and user experience
+- 💡 **Actionable Insights**: Generates 3-5 specific improvement suggestions
+- 🤖 **AI-Powered**: Uses Hyperbrowser's CUA agent for intelligent page analysis
 
-- Automatically identifies the main CTA button in a website's hero section
-- Analyzes CTA buttons for accessibility and SEO best practices
-- Checks color contrast, text clarity, and positioning
-- Provides 3-5 specific improvement suggestions
+## 🔧 Installation
 
-## Requirements
+1. Install dependencies:
+```bash
+npm install
+```
 
-- Node.js
-- Hyperbrowser API key (get your API keys at hyperbrowser.ai)
+2. **Get an API key** at [https://hyperbrowser.ai](https://hyperbrowser.ai)
 
-## Installation
+3. Set up environment variables:
+```bash
+# Create a .env file
+echo "HYPERBROWSER_API_KEY=your_key_here" > .env
+```
 
-1. Clone the repository
-2. Install dependencies:
+## 🚀 Quick Start
 
 ```bash
+# Install dependencies
 npm install
+
+# Set environment variable
+export HYPERBROWSER_API_KEY="your_key_here"
+
+# Run with URL argument
+npx tsx cua-cta-validator.ts https://example.com
+
+# Or run interactively (will prompt for URL)
+npx tsx cua-cta-validator.ts
 ```
 
-3. Create a `.env` file in the root directory with your Hyperbrowser API key:
+## 💡 Usage Examples
 
+### Validate a Landing Page
+```bash
+npx tsx cua-cta-validator.ts https://productland.com
+```
+
+### Analyze a SaaS Homepage
+```bash
+npx tsx cua-cta-validator.ts https://yourapp.com/pricing
 ```
-HYPERBROWSER_API_KEY=your_api_key_here
+
+### Check E-commerce CTA
+```bash
+npx tsx cua-cta-validator.ts https://shop.example.com
 ```
 
-## Usage
+## 🎯 What Gets Analyzed
+
+The tool performs a three-step analysis:
+
+### Step 1: CTA Identification
+- Locates the primary CTA button in the hero section
+- Ignores secondary CTAs and other page sections
+- Captures button text, styling, and position
 
-Run the validator by providing a URL as a command-line argument:
+### Step 2: Accessibility & SEO Analysis
+- **Color Contrast**: WCAG compliance check
+- **Text Clarity**: Readability and action-oriented copy
+- **Positioning**: Visual hierarchy and fold placement
+- **Semantic HTML**: Proper button/link usage
+- **Mobile Responsiveness**: Touch target size
+
+### Step 3: Improvement Suggestions
+- 3-5 actionable recommendations
+- Prioritized by impact on conversion
+- Based on industry best practices
+
+## 🔑 Environment Variables
 
 ```bash
-npm start -- https://example.com
+HYPERBROWSER_API_KEY    # Required - Get at https://hyperbrowser.ai
 ```
 
-Or run without arguments to be prompted for a URL:
+## 🏗️ How It Works
 
-```bash
-npm start
+1. **Session Creation**: Initializes a Hyperbrowser session with CUA agent
+2. **Navigation**: Opens the target URL in a real browser environment
+3. **CTA Detection**: AI agent identifies the primary hero CTA button
+4. **Analysis**: Evaluates accessibility, SEO, and UX best practices
+5. **Suggestions**: Generates specific, actionable improvements
+6. **Cleanup**: Closes the browser session
+
+## 📊 Output Format
+
+```
+Starting CTA Validator Agent...
+Validating CTA buttons on: https://example.com
+
+Step 1: Identifying CTA button in hero section...
+Output:
+Main CTA button found: "Get Started Free" - Blue button with white text...
+
+Step 2: Analyzing CTA for accessibility and SEO...
+Analysis:
+• Color contrast: 4.8:1 (passes WCAG AA)
+• Text clarity: Action-oriented and clear
+• Positioning: Above the fold, centered...
+
+Step 3: Generating improvement suggestions...
+Suggestions:
+1. Increase color contrast to 7:1 for WCAG AAA compliance
+2. Add aria-label for better screen reader support
+3. Consider A/B testing "Start Free Trial" for higher conversion
+4. Increase button size for better mobile touch targets
+5. Add subtle animation to draw attention
 ```
 
-## How It Works
+## 🎛️ Technical Details
+
+- **Agent**: Uses `@hyperbrowser/sdk` with CUA (Conversational User Agent)
+- **Runtime**: TypeScript with `tsx` for execution
+- **Schema Validation**: Zod for type-safe output parsing
+- **Session Management**: Keeps browser open between steps for efficiency
+- **Max Steps**: Configurable limits per analysis phase (15-20 steps)
+
+## 🎯 Use Cases
 
-1. The tool connects to the Hyperbrowser API using your API key
-2. It navigates to the specified URL
-3. Step 1: Identifies the main CTA button in the hero section
-4. Step 2: Analyzes the CTA for accessibility and SEO best practices
-5. Step 3: Generates specific improvement suggestions
+- **UX Audits**: Validate CTA effectiveness across multiple pages
+- **A/B Testing Prep**: Identify improvement opportunities before testing
+- **Accessibility Compliance**: Ensure CTAs meet WCAG standards
+- **Competitor Analysis**: Benchmark your CTAs against competitors
+- **Conversion Optimization**: Data-driven suggestions for higher conversions
+
+## 📦 Dependencies
+
+- `@hyperbrowser/sdk` - Official Hyperbrowser SDK for browser automation
+- `@hyperbrowser/agent` - CUA agent capabilities
+- `dotenv` - Environment variable management
+- `zod` - Runtime type validation
+- `typescript` + `ts-node` - TypeScript execution
+
+## 🔄 Development
+
+```bash
+# Run in development mode
+npx tsx cua-cta-validator.ts https://example.com
+
+# With verbose output
+DEBUG=* npx tsx cua-cta-validator.ts https://example.com
+```
 
-## Dependencies
+---
 
-- @hyperbrowser/sdk - For interacting with Hyperbrowser
-- dotenv - For loading environment variables
-- zod - For runtime type checking
+Follow [@hyperbrowser](https://x.com/hyperbrowser) for updates.