CBrowser — Cognitive Browser Automation

The browser automation that thinks. Achieved Grade A+ in comprehensive stress testing—100% pass rate across 91 tools, zero critical bugs, zero server crashes. View Full Assessment →

Built for AI agents. Trusted by humans. The only browser automation that asks: "Will a confused first-timer complete this task—and exactly when will they give up?"

Sites that pass CBrowser's cognitive tests are easier for both humans and AI agents to navigate. The same principles that reduce user friction—clear structure, predictable patterns, accessible design—make sites more reliable for autonomous AI.

What Makes CBrowser Different

91 tools, 17 cognitive personas, 25 research-backed traits. After rigorous stress testing across production sites including Airbnb and Hacker News:

The Problem We Solve

Traditional browser automation answers one question: "Does this button click?"

CBrowser answers the question that actually matters: "Will a confused first-timer on a slow connection find this button—and will they give up before they do?"

Built on Playwright with cognitive user simulation, constitutional AI safety, and research-backed behavioral models, CBrowser is the only testing framework designed for the AI agent era.

Core Differentiators

Quick Start

Installation

npm install cbrowser
npx playwright install chromium

First Commands

# Navigate with intelligent wait detection
npx cbrowser navigate "https://your-site.com"

# Self-healing click with 80%+ confidence threshold
npx cbrowser smart-click "Add to Cart"

# Natural language assertions
npx cbrowser assert "page contains 'Order Confirmed'"

# Run a cognitive journey—simulate a real user
npx cbrowser cognitive-journey \
  --persona first-timer \
  --start "https://your-site.com" \
  --goal "complete checkout"

Constitutional AI Safety

AI agents need boundaries. CBrowser classifies every action by risk level:

An AI agent can freely browse and gather data, but cannot accidentally submit a form, delete records, or make purchases without explicit verification.

Cognitive User Simulation

CBrowser models 25 research-backed cognitive traits across 6 tiers to simulate how real users think and behave:

See Trait Index for all 25 traits including: Persistence, Resilience, Curiosity, Change Blindness, Anchoring Bias, Time Horizon, Attribution Style, Metacognitive Planning, Procedural Fluency, Transfer Learning, Authority Sensitivity, Emotional Contagion, Mental Model Rigidity, Interrupt Recovery, and Reading Tendency.

Note: Trait correlation values are educated estimates derived from related research. Empirical calibration planned per GitHub #95.

Full documentation: Research Methodology · Trait Index · Bibliography

Abandonment Detection

The simulation stops when a realistic user would give up:

# Output from cognitive journey
⚠️ ABANDONED after 8 steps
Reason: Patience depleted (0.08) - "This is taking too long..."
Friction points:
  1. Password requirements unclear (step 4)
  2. Form validation error not visible (step 6)

Custom Persona Builder (v16.6.0)

Create research-backed custom personas via interactive questionnaire:

# Interactive questionnaire (8 core traits)
npx cbrowser persona-questionnaire start

# Comprehensive questionnaire (all 25 traits)
npx cbrowser persona-questionnaire start --comprehensive --name "my-tester"

# Look up trait behaviors
npx cbrowser persona-questionnaire lookup --trait patience --value 0.25

# List all available traits
npx cbrowser persona-questionnaire list-traits

Each trait maps to research-backed behavioral descriptions with 5 levels (0, 0.25, 0.5, 0.75, 1.0).

Research-Backed Values System (v16.12.0)

Beyond cognitive traits, CBrowser models motivational values that drive user decisions. The values system integrates three foundational psychological frameworks:

Values influence decision-making differently than cognitive traits. A user high in Security values will read privacy policies; one high in Stimulation will click "Try Beta Features" immediately.

# Look up a persona's values profile
npx cbrowser persona-values power-user

# Output shows Schwartz values, SDT needs, and Maslow level

Category-Aware Persona Creation

When you create a custom persona via persona-questionnaire, CBrowser automatically assigns appropriate values based on persona category:

This ensures cognitive journeys reflect realistic motivational differences—not just skill gaps. See Persona Values Documentation for the complete values framework.

Natural Language Testing

Write tests in plain English:

# Test: Checkout Flow
go to https://your-site.com/products
click "Add to Cart" button
verify page contains "1 item in cart"
click checkout
fill email with "[email protected]"
click "Place Order"
verify url contains "/confirmation"

npx cbrowser test-suite checkout-test.txt --html

Self-Healing Test Repair

When tests break due to site changes:

npx cbrowser repair-tests broken-test.txt --auto-apply --verify

CBrowser analyzes failures, generates alternative selectors, and repairs tests automatically.

Visual Testing Suite

AI Visual Regression

Semantic comparison—understands what changed, not just pixel differences:

npx cbrowser ai-visual capture "https://your-site.com" --name homepage
npx cbrowser ai-visual test "https://staging.your-site.com" homepage --html

Cross-Browser & Responsive

# Compare Chrome, Firefox, Safari rendering
npx cbrowser cross-browser "https://your-site.com" --html

# Test across mobile, tablet, desktop
npx cbrowser responsive "https://your-site.com" --html

# A/B comparison (staging vs production)
npx cbrowser ab "https://staging.your-site.com" "https://your-site.com" --html

UX Analysis Suite

Agent-Ready Audit

Analyze any website for AI-agent friendliness:

npx cbrowser agent-ready-audit "https://your-site.com" --html

Returns:

• Findability score — Can agents locate elements? (ARIA labels, semantic HTML)
• Stability score — Will selectors break? (hidden inputs, overlays)
• Letter grade (A-F) with prioritized remediation and code examples

Competitive UX Benchmark

Run identical cognitive journeys across your site and competitors:

npx cbrowser competitive-benchmark \
  --sites "https://your-site.com,https://competitor-a.com,https://competitor-b.com" \
  --goal "sign up for free trial" \
  --persona first-timer \
  --html

Accessibility Empathy Mode

Simulate how users with disabilities experience your site:

npx cbrowser empathy-audit "https://your-site.com" \
  --goal "complete signup" \
  --disabilities "motor-tremor,low-vision,adhd" \
  --html

Available personas: motor-tremor, low-vision, cognitive-adhd, dyslexic, deaf, elderly

MCP Server Integration

CBrowser runs as an MCP server for Claude Desktop and claude.ai.

Remote MCP (claude.ai)

Public Demo Server (rate-limited, no auth):

https://demo.cbrowser.ai/mcp

Deploy your own: see Remote MCP Server Guide

v18.13.0+: Screenshots automatically compress to JPEG in remote mode to stay under claude.ai's 200KB tool response limit. Compression is adaptive (quality 85→25, scales down if needed).

Local MCP (Claude Desktop)

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

91 MCP Tools

CI/CD Integration

GitHub Actions

name: CBrowser Tests
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: alexandriashai/cbrowser@v12
        with:
          test-file: tests/e2e/checkout.txt
          sensitivity: strict

Docker

docker run --rm -v $(pwd)/tests:/work/tests ghcr.io/alexandriashai/cbrowser:latest \
  test-suite tests/checkout.txt --html

Modular Architecture

Tree-shakeable imports for minimal bundle size:

// Import specific modules
import { runVisualRegression, runCrossBrowserTest } from 'cbrowser/visual';
import { runNLTestSuite, detectFlakyTests, repairTest } from 'cbrowser/testing';
import { huntBugs, runChaosTest, findElementByIntent } from 'cbrowser/analysis';
import { capturePerformanceBaseline, detectPerformanceRegression } from 'cbrowser/performance';

API Reference

import { CBrowser } from 'cbrowser';

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

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

const result = await browser.smartClick('Sign In', {
  maxRetries: 3,
  minConfidence: 0.8  // v12.0.0: Raised threshold for reliable healing
});

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

await browser.close();

Configuration

Environment Variables

API Key (for Cognitive Journeys)

npx cbrowser config set-api-key

Token Cost & Selective Loading

CBrowser's 91 MCP tools consume approximately ~38,000 tokens when loaded into an LLM context. For cost-sensitive applications, use selective tool loading:

Tool Categories (for programmatic use):

Programmatic selective loading:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import {
  registerNavigationTools,
  registerInteractionTools,
  registerExtractionTools,
} from "cbrowser/mcp-tools";

const server = new McpServer({ name: "my-app", version: "1.0.0" });
const context = { getBrowser: () => browser };

// Only load what you need (~5,000 tokens instead of ~38,000)
registerNavigationTools(server, context);
registerInteractionTools(server, context);
registerExtractionTools(server, context);

Full category list: navigation, interaction, extraction, assertion, analysis, session, healing, visualTesting, testing, bugAnalysis, personaComparison, cognitive, values, performance, audit, browserManagement, security, marketing, remediation, llmsTxt.

Examples

Enterprise Edition

CBrowser Enterprise extends CBrowser with:

MCP Server: Enterprise MCP includes all 64 base tools + marketing tools (4 active + 4 planned).

# Start Enterprise MCP server
npx cbrowser-enterprise mcp-server

# List marketing personas
npx cbrowser-enterprise marketing personas list --category b2b

See Marketing Suite Wiki for full documentation.

License

MIT License — Free and open source.

Use, modify, and distribute freely for any purpose, including commercial and production use. See LICENSE for full terms.

Copyright

© 2026 Alexandria Eden

Contact: [email protected]
Website: cbrowser.ai

Links

• 📚 Documentation — Full documentation, guides, and API reference
• NPM Package
• GitHub Repository
• Issue Tracker
• A+ Assessment Report
• Roadmap

Research Documentation

• Research Methodology — How 25 traits were selected and validated
• Trait Index — All cognitive traits with citations
• Bibliography — Complete academic references
• Persona Index — All 17 built-in personas