CBrowser

The only browser automation that asks: "Can a real user complete this safely?"

Most AI automation tools ask if a task can be completed. CBrowser asks if an elderly first-timer on mobile can complete it—and whether the automation should even be allowed to try.

Why CBrowser Exists

Every AI browser tool now has self-healing selectors and natural language commands. That's table stakes.

CBrowser solves three problems no one else does:

1. Constitutional AI Safety (No One Else Has This)

Other tools will happily click "Delete All Data" or "Transfer $10,000" if you ask. CBrowser classifies every action by risk:

This isn't just guardrails—it's the only AI browser automation with built-in ethical boundaries.

2. User Perspective Testing (Not Just "Does It Work?")

Other tools test if buttons click. CBrowser tests if real humans can use your site:

npx cbrowser compare-personas \
  --start "https://your-site.com" \
  --goal "Complete checkout" \
  --personas power-user,elderly-user,mobile-user

Each persona has realistic human behavior: reaction times, typo rates, mouse jitter, attention patterns. You'll discover that your checkout works fine for developers but fails for 40% of real users.

3. Claude-Native MCP Integration

Built for the Claude ecosystem. Add to Claude Desktop and get browser automation as a native capability—no API keys, no external services, no vendor lock-in.

Feature Comparison

Also Included (Table Stakes)

Quick Start

Installation

# npm
npm install cbrowser

# bun (recommended)
bun add cbrowser

# yarn
yarn add cbrowser

Install Playwright Browsers

npx playwright install chromium

Basic Usage

# Navigate to a URL
npx cbrowser navigate "https://example.com"

# Click with auto-retry and self-healing
npx cbrowser smart-click "Add to Cart"

# Natural language assertions
npx cbrowser assert "page contains 'Welcome'"

# Generate tests from any page
npx cbrowser generate-tests "https://example.com"

v6.0.0 Features

Multi-Persona Comparison

Run the same journey with multiple personas in parallel and compare results:

# Compare how different user types experience your site
npx cbrowser compare-personas \
  --start "https://example.com" \
  --goal "Complete checkout" \
  --personas power-user,first-timer,elderly-user,mobile-user

# Output:
# ┌─────────────────┬──────────┬──────────┬──────────┬─────────────────┐
# │ Persona         │ Success  │ Time     │ Friction │ Key Issues      │
# ├─────────────────┼──────────┼──────────┼──────────┼─────────────────┤
# │ power-user      │ ✓        │ 12.5s    │ 0        │ -               │
# │ first-timer     │ ✓        │ 45.2s    │ 2        │ Confusing CTA   │
# │ elderly-user    │ ✗        │ 120.3s   │ 5        │ Small buttons   │
# │ mobile-user     │ ✓        │ 28.1s    │ 1        │ Scroll issue    │
# └─────────────────┴──────────┴──────────┴──────────┴─────────────────┘

Generate reports:

# JSON report
npx cbrowser compare-personas --start "..." --goal "..." --output report.json

# HTML report (visual dashboard)
npx cbrowser compare-personas --start "..." --goal "..." --html

What you learn:

• Which personas struggle most (friction points)
• Time differences between expert and beginner users
• Mobile vs desktop experience gaps
• Accessibility issues affecting specific user types
• Actionable recommendations for improvement

Automatic recommendations:

• "Beginners take 3.5x longer than experts - consider adding more guidance"
• "Mobile users experience 2x more friction - review mobile UX"
• "Common friction: 'Button too small for touch', 'Form validation unclear'"

v6.2.0 Features

AI Test Repair

Automatically analyze failing tests and suggest or apply repairs:

# Analyze a broken test and see repair suggestions
npx cbrowser repair-tests broken-test.txt

# Automatically apply the best repairs
npx cbrowser repair-tests tests.txt --auto-apply

# Apply repairs and verify they work
npx cbrowser repair-tests tests.txt --auto-apply --verify

# Save repaired tests to a new file
npx cbrowser repair-tests tests.txt --auto-apply --output fixed-tests.txt

What it analyzes:

Example output:

🔧 Analyzing test: Login Flow

   → click the signin button
     ✗ Failed: Failed to click: signin button
     💡 Suggestions:
        - Update selector to "Login" (70%)
          → click "Login"
        - Add wait before this step (50%)
          → wait 2 seconds

📊 SUMMARY
  Total Failed Steps: 1
  Repair Success Rate: 100%

API usage:

import { repairTestSuite, formatRepairReport, exportRepairedTest } from 'cbrowser';

const result = await repairTestSuite(suite, {
  autoApply: true,
  verifyRepairs: true,
});

console.log(formatRepairReport(result));

// Export repaired test to file format
for (const testResult of result.testResults) {
  console.log(exportRepairedTest(testResult));
}

v6.3.0 Features

Flaky Test Detection

Identify unreliable tests by running them multiple times and analyzing consistency:

# Run tests 5 times (default) and detect flakiness
npx cbrowser flaky-check tests.txt

# Custom number of runs
npx cbrowser flaky-check tests.txt --runs 10

# Set custom flakiness threshold (default: 20%)
npx cbrowser flaky-check tests.txt --threshold 30

# Save report to file
npx cbrowser flaky-check tests.txt --output flaky-report.json

What it measures:

Example output:

🔍 FLAKY TEST DETECTION REPORT
══════════════════════════════════════════════════════════════

📋 Suite: Login Tests
   Runs per test: 5
   Total duration: 45.2s

──────────────────────────────────────────────────────────────
TEST RESULTS
──────────────────────────────────────────────────────────────

✅ STABLE_PASS (5/5 passed, flakiness: 0%)
   Login Flow
   └─ Avg duration: 2.1s (±0.1s)

⚠️  FLAKY (3/5 passed, flakiness: 80%)
   Search Functionality
   └─ Avg duration: 3.5s (±1.2s)
   └─ Flaky steps:
      • wait for "Loading" appears (60% flaky)
      • verify page contains "results" (40% flaky)

══════════════════════════════════════════════════════════════
📊 SUMMARY
══════════════════════════════════════════════════════════════

✅ Overall Flakiness: 40%
   Stable tests: 1 | Flaky tests: 1

⚠️  Most flaky test: Search Functionality (80%)
⚠️  Most flaky step: wait for "Loading" appears (60%)

💡 RECOMMENDATIONS
• Search Functionality: Add explicit waits, increase timeout
• wait for "Loading" appears: Use more specific selector

API usage:

import { parseNLTestSuite, detectFlakyTests, formatFlakyTestReport } from 'cbrowser';

const suite = parseNLTestSuite(testContent, "My Tests");

const result = await detectFlakyTests(suite, {
  runs: 10,
  flakinessThreshold: 25,
  delayBetweenRuns: 1000,
});

console.log(formatFlakyTestReport(result));

// Access detailed analysis
for (const test of result.testAnalyses) {
  if (test.isFlaky) {
    console.log(`${test.testName}: ${test.flakinessScore}% flaky`);
    for (const step of test.stepAnalysis) {
      if (step.isFlaky) {
        console.log(`  └─ ${step.instruction}: ${step.flakinessScore}% flaky`);
      }
    }
  }
}

v6.1.0 Features

Natural Language Test Suites

Write tests in plain English - CBrowser parses and executes them:

# Run tests from a file
npx cbrowser test-suite login-test.txt --html

# Run inline tests (steps separated by semicolons)
npx cbrowser test-suite --inline "go to https://example.com ; click login ; verify url contains /dashboard"

Test file format:

# Test: Login Flow
go to https://example.com
click the login button
type "user@example.com" in email field
type "password123" in password field
click submit
verify url contains "/dashboard"

# Test: Search Functionality
go to https://example.com/search
type "test query" in search box
click search button
verify page contains "results"
take screenshot

Supported instructions:

Output options:

# Continue after failures
npx cbrowser test-suite tests.txt --continue-on-failure

# Save JSON report
npx cbrowser test-suite tests.txt --output results.json

# Generate HTML report
npx cbrowser test-suite tests.txt --html

# Combined
npx cbrowser test-suite tests.txt --output results.json --html

API usage:

import { parseNLTestSuite, runNLTestSuite, formatNLTestReport } from 'cbrowser';

const suite = parseNLTestSuite(`
  # Test: Homepage
  go to https://example.com
  verify title contains "Example"
  click the about link
  verify url contains "/about"
`, "My Test Suite");

const result = await runNLTestSuite(suite, {
  continueOnFailure: true,
  screenshotOnFailure: true,
});

console.log(formatNLTestReport(result));
// Pass rate: 100%
// Tests: 1 passed, 0 failed

v5.0.0 Features

Smart Click with Auto-Retry

When an element isn't found, CBrowser automatically:

1. Checks the self-healing cache for known alternatives
2. Generates alternative selectors (text variants, ARIA roles, attributes)
3. Tries each alternative with configurable retry logic
4. Caches working selectors for future use

# Smart click with retry
npx cbrowser smart-click "Submit" --max-retries 5

# Navigate then click
npx cbrowser smart-click "Login" --url "https://example.com"

import { CBrowser } from 'cbrowser';

const browser = new CBrowser();
const result = await browser.smartClick("Submit Button", { maxRetries: 3 });

console.log(result.success);        // true/false
console.log(result.finalSelector);  // The selector that worked
console.log(result.attempts);       // Array of all attempts
console.log(result.aiSuggestion);   // AI suggestion if failed

Natural Language Assertions

Write assertions in plain English:

# Title assertions
npx cbrowser assert "title contains 'Dashboard'"
npx cbrowser assert "title is 'Home Page'"

# URL assertions
npx cbrowser assert "url contains '/login'"

# Content assertions
npx cbrowser assert "page contains 'Welcome back'"

# Element assertions
npx cbrowser assert "'#submit-btn' exists"

# Count assertions
npx cbrowser assert "5 buttons"
npx cbrowser assert "3 links"

const result = await browser.assert("page contains 'Success'");
console.log(result.passed);   // true/false
console.log(result.message);  // Human-readable result
console.log(result.actual);   // What was found
console.log(result.expected); // What was expected

Self-Healing Selector Cache

CBrowser remembers which selectors work on each domain:

# View cache statistics
npx cbrowser heal-stats

# Clear the cache
npx cbrowser heal-clear

const stats = browser.getSelectorCacheStats();
console.log(stats.totalEntries);    // 42
console.log(stats.totalSuccesses);  // 156
console.log(stats.topDomains);      // [{ domain: 'example.com', count: 15 }, ...]

AI Test Generation

Analyze any page and generate test scenarios automatically:

# Generate tests for a page
npx cbrowser generate-tests "https://example.com"

# Output specific format
npx cbrowser generate-tests "https://example.com" --format playwright
npx cbrowser generate-tests "https://example.com" --format cbrowser

# Save to file
npx cbrowser generate-tests "https://example.com" --output tests.ts

const result = await browser.generateTests("https://example.com");

console.log(result.analysis);       // Page structure analysis
console.log(result.tests);          // Generated test scenarios
console.log(result.playwrightCode); // Playwright test code
console.log(result.cbrowserScript); // CBrowser CLI script

Example generated test:

test('Login - Valid Credentials', async ({ page }) => {
  await page.goto('https://example.com');
  await page.locator('[name="email"]').fill('test@example.com');
  await page.locator('[name="password"]').fill('password123');
  await page.locator('button[type="submit"]').click();
  await expect(page).toHaveURL(/dashboard/);
});

Page Analysis

Understand any page's structure:

npx cbrowser analyze "https://example.com"

Output:

📊 Page Analysis:
   Title: Example Domain
   Forms: 1
     - form#login (3 fields)
       🔐 Login form detected
   Buttons: 5
   Links: 12
   Has Login: ✅
   Has Search: ❌
   Has Navigation: ✅

MCP Server Mode

Run CBrowser as an MCP server for Claude Desktop integration:

npx cbrowser mcp-server

Add to Claude Desktop config (~/.config/claude-desktop/config.json):

{
  "mcpServers": {
    "cbrowser": {
      "command": "npx",
      "args": ["cbrowser", "mcp-server"]
    }
  }
}

Available MCP Tools:

• navigate - Navigate to URL and screenshot
• click / smart_click - Click elements
• fill - Fill form fields
• screenshot - Capture page
• extract - Extract page data
• assert - Natural language assertions
• analyze_page - Analyze page structure
• generate_tests - Generate test scenarios
• save_session / load_session - Session management
• heal_stats - Self-healing cache stats

Core Features

AI-Powered Element Selection

# Natural language
cbrowser click "the main navigation menu"
cbrowser fill "password field" "secret123"

# Accessibility-based
cbrowser click "aria:button/Submit"

# Visual description
cbrowser click "visual:red button in header"

# Semantic type
cbrowser fill "semantic:email" "user@example.com"

# Fallback to CSS
cbrowser click "css:#login-btn"

Session Persistence

# Save session (cookies, localStorage, sessionStorage)
cbrowser session save "logged-in" --url "https://example.com"

# Load session
cbrowser session load "logged-in"

# List sessions
cbrowser session list

Persistent Browser Context

Enable persistent mode to keep cookies and localStorage between CLI calls:

npx cbrowser navigate "https://example.com" --persistent

Persona-Driven Testing

# Run autonomous journey as a persona
cbrowser journey "first-timer" \
  --start "https://mysite.com" \
  --goal "Complete signup"

# List personas
cbrowser persona list

Built-in Personas:

AI Persona Creation (v5.3.0):

Create custom personas from natural language descriptions:

# Describe the user - AI generates all parameters
npx cbrowser persona create "impatient developer who hates slow UIs" --name speed-demon
npx cbrowser persona create "elderly grandmother new to computers with tremors" --name grandma
npx cbrowser persona create "distracted teenager on their phone"

# List all personas (built-in + custom)
npx cbrowser persona list

# View full persona config
npx cbrowser persona show speed-demon

# Export/import for sharing
npx cbrowser persona export speed-demon
npx cbrowser persona import custom-persona.json

# Delete custom persona
npx cbrowser persona delete speed-demon

The AI analyzes your description and generates appropriate:

• Timing: reaction times, click delays, typing speed
• Error rates: misclicks, typos, accidental double-clicks
• Mouse behavior: movement speed, jitter, overshoot
• Attention patterns: reading style, scroll behavior, focus areas
• Viewport: device-appropriate screen size

Multi-Browser Support

# Firefox
npx cbrowser navigate "https://example.com" --browser firefox

# WebKit (Safari)
npx cbrowser navigate "https://example.com" --browser webkit

Device Emulation

# Mobile
npx cbrowser navigate "https://example.com" --device iphone-15

# Tablet
npx cbrowser navigate "https://example.com" --device ipad-pro-12

# List devices
npx cbrowser device list

Performance Metrics

# Core Web Vitals
npx cbrowser perf "https://example.com"

# With budget
npx cbrowser perf audit "https://example.com" --budget-lcp 2500

API Usage

import { CBrowser } from 'cbrowser';

const browser = new CBrowser({
  headless: true,
  persistent: true,  // Persist cookies between sessions
});

// Navigate
await browser.navigate('https://example.com');

// Smart click with retry
const clickResult = await browser.smartClick('Sign In');

// Fill form
await browser.fill('email', 'user@example.com');

// Assert
const assertion = await browser.assert("page contains 'Welcome'");
if (!assertion.passed) {
  console.error(assertion.message);
}

// Generate tests
const tests = await browser.generateTests();
console.log(tests.playwrightCode);

// Cleanup
await browser.close();

Configuration

Environment Variables

Config File

Create .cbrowserrc.json:

{
  "headless": true,
  "timeout": 60000,
  "persistent": true,
  "viewport": {
    "width": 1920,
    "height": 1080
  }
}

Constitutional Safety

CBrowser classifies actions by risk level:

# Bypass safety for testing
cbrowser click "Delete Account" --force

Performance

CBrowser uses optimized Chromium launch flags for fast startup:

• ~1 second browser cold start (vs 3-5s default)
• Persistent context keeps cookies between calls
• Self-healing cache reduces retry overhead

Examples

See the examples/ directory:

• basic-usage.ts - Navigation, extraction, sessions
• smart-automation.ts - Smart click, assertions, test generation
• journeys/checkout-flow.json - Persona journey definition
• personas/custom-persona.json - Custom persona template

Troubleshooting

Browser Not Starting

npx playwright install chromium --force

Display Issues (Linux)

CBrowser runs headless by default. For GUI mode:

CBROWSER_HEADLESS=false npx cbrowser navigate "https://example.com"

Self-Healing Not Working

# Check cache status
npx cbrowser heal-stats

# Clear if corrupted
npx cbrowser heal-clear

Contributing

git clone https://github.com/alexandriashai/cbrowser.git
cd cbrowser
bun install
bun run dev

See CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE

Links

• NPM Package
• GitHub Repository
• Issue Tracker
• Roadmap