CBrowser — Cognitive Browser Automation

The browser automation that thinks like your users. 120 MCP tools. 26 cognitive traits. 11 disability personas. The only framework that predicts when users give up.

npm install cbrowser
npx cbrowser cognitive-effort --url "https://your-site.com" --persona first-timer

---

5-Minute Quickstart

Get from zero to your first cognitive insight in 3 commands:

# 1. Install CBrowser
npm install cbrowser

# 2. Install the browser engine (~150MB)
npx playwright install chromium

# 3. Run your first cognitive audit
npx cbrowser cognitive-effort --url "https://your-site.com" --persona first-timer

What you get: A cognitive transport score (0-1), abandonment risk percentage, and the UX bottleneck — in under 30 seconds.

No API key needed for basic commands (navigate, screenshot, click, extract, explore). Cognitive journeys require an Anthropic API key:

npx cbrowser config set-api-key <your-anthropic-key>

Check your environment: Run npx cbrowser doctor to verify everything is set up correctly.

Accessibility: CBrowser supports --no-color (or NO_COLOR env var), --plain (no emoji/decorations), and --json-output (structured JSON) for screen readers, CI pipelines, and scripting.

---

Table of Contents

• 5-Minute Quickstart
• Cognitive Transport Chain
• Visual Overlays & Attention Analysis
• AI Friendliness Suite
• Cognitive User Simulation
• Accessibility Empathy Testing
• Constitutional AI Safety
• Site Knowledge System
• Natural Language Testing
• Visual Testing
• Competitive UX Benchmark
• Geo Proxy
• MCP Server Integration
• CI/CD Integration
• API Reference
• Configuration
• Enterprise Edition
• Contributing
• License

---

Cognitive Transport Chain

The 6-layer Sequential Transport Chain computes exactly how hard your page is for any persona — and predicts whether they'll abandon:

Layer	What It Measures	Research Basis
Saliency	Visual attention capture	CIE-Lab W₂ perceptual model
Cognitive Load	Information processing demand	Sweller (1988) CLT
Decision	Choice complexity and fatigue	Hick-Hyman Law
Motor	Physical interaction difficulty	Grossman & Balakrishnan (2005)
Frustration	Emotional cost accumulation	Ceaparu et al. (2004)
Readability	Text comprehension effort	Perry & Zorzi (2013) reading model

npx cbrowser cognitive-effort --url "https://your-site.com" --persona first-timer
# → CTC: 0.76, abandonment risk: 42%, bottleneck: decision

Returns: total CTC score, per-layer breakdown, bottleneck identification, abandonment risk percentage, and motor accessibility overlay.

---

Visual Overlays & Attention Analysis

See where users look, what they miss, and whether your CTAs capture attention — per persona:

# Full visual cognitive story — 4 annotated images + narrative
npx cbrowser visual-cognitive-story --url "https://your-site.com" --persona cognitive-adhd

# Attention heatmap — where does this persona look?
npx cbrowser attention-analysis --url "https://your-site.com" --persona first-timer

# Compare how two personas experience the same page
npx cbrowser attention-compare --url "https://your-site.com" --persona-a first-timer --persona-b power-user

Overlays generated:

• Attention heatmap — CIE-Lab saliency on grayscale base (red = high attention)
• Motor accessibility — Green/yellow/red per element by P(hit)
• Attention quality — CTAs green, distractors red, headings blue
• Comparison diff — Blue = persona A attention, red = persona B

Metrics: CTA capture rate, value prop salience, distractor ratio, quality score (0-100), entropy.

---

AI Friendliness Suite

Five tools to make your site ready for the AI agent era:

Tool	What It Does
agent_ready_audit	Score site on findability, stability, accessibility, semantics (A-F grade)
ai_benchmark	Compare AI-friendliness across competitor URLs
webmcp_ready_audit	Audit MCP server for WebMCP compatibility
remediation_patches	Generate actionable code fixes for audit findings
llms_txt_generate	Generate AI-readable llms.txt site description

npx cbrowser agent-ready-audit "https://your-site.com" --html
npx cbrowser ai-benchmark "https://site-a.com,https://site-b.com"

---

Cognitive User Simulation

26 research-backed cognitive traits + 10 motivational values model how real users think, struggle, and give up:

Trait	Research Basis	What It Models
Patience	Nah (2004); Nielsen (1993)	Tolerance for delays; abandonment at 8+ seconds
Working Memory	Miller (1956)	7±2 item capacity; affects form complexity tolerance
Comprehension	Card, Moran & Newell (1983)	UI convention understanding; GOMS model timing
Risk Tolerance	Kahneman & Tversky (1979)	Prospect theory; loss aversion affects CTA clicks
Self-Efficacy	Bandura (1977)	Belief in ability to solve problems; low = faster abandonment
Satisficing	Simon (1956)	Accept "good enough" vs. optimize; 50% faster decisions
Trust Calibration	Fogg (2003)	8 trust signals; affects click-through by 40%
Information Foraging	Pirolli & Card (1999)	"Scent" following behavior; predicts navigation patterns
Social Proof	Cialdini (2001)	Influence of reviews, ratings, popularity indicators
FOMO	Przybylski et al. (2013)	Fear of missing out; urgency and scarcity responses

See Trait Index for all 26 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, Reading Tendency, and Site Familiarity.

Full documentation: Research Methodology · Trait Index · Bibliography

17 Built-in Personas

6 general: first-timer, power-user, mobile-user, screen-reader-user, elderly-user, impatient-user

11 accessibility: motor-impairment-tremor, low-vision-magnified, cognitive-adhd, dyslexic-user, deaf-user, elderly-low-vision, color-blind-deuteranopia, autism-spectrum, intellectual-disability, aphasia-receptive, dyscalculia

Values System

Beyond cognitive traits, CBrowser models 10 motivational values from three psychological frameworks:

Framework	Research Basis
Schwartz's Universal Values	Schwartz (1992) — 10 core values: Power, Achievement, Hedonism, Stimulation, Self-Direction, Universalism, Benevolence, Tradition, Conformity, Security
Self-Determination Theory	Deci & Ryan (1985) — Autonomy, Competence, Relatedness
Maslow's Hierarchy	Maslow (1943) — 5 need levels

See Values Framework for full documentation.

Custom Persona Builder

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

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

# From a description — AI generates trait values
npx cbrowser persona-create "A 68-year-old retiree who just got their first smartphone"

Abandonment Detection

The simulation stops when a realistic user would give up:

⚠️ 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)

---

Accessibility Empathy Testing

Simulate how users with disabilities experience your site:

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

---

Constitutional AI Safety

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

Zone	Examples	Behavior
🟢 Green	Navigate, read, screenshot	Auto-execute
🟡 Yellow	Click buttons, fill forms	Log and proceed
🔴 Red	Submit, delete, purchase	Requires verification
⬛ Black	Bypass auth, inject scripts	Never executes

---

Site Knowledge System

CBrowser learns your site over time:

• Page Understanding — DOM analysis, page type classification, available affordances
• Site Model Learning — Persistent knowledge graph across sessions
• Cross-Session Profiles — AES-256-GCM encrypted cookie/state profiles
• Goal Decomposition — Sub-goal trees with fallback strategies

---

Natural Language Testing

# 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 "test@example.com"
click "Place Order"
verify url contains "/confirmation"

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

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

---

Visual Testing

# AI visual regression
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 (Chrome, Firefox, Safari)
npx cbrowser cross-browser "https://your-site.com" --html

# Responsive (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

---

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

---

Geo Proxy

Test from 12 global regions via residential proxies:

npx cbrowser cognitive-journey \
  --start "https://your-site.com" \
  --persona first-timer \
  --goal "sign up" \
  --geo-region uk

Regions: us-west, us-east, us-central, uk, germany, france, japan, australia, brazil, india, canada, singapore

---

MCP Server Integration

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

Claude.ai (Easiest — No Install)

Add the MCP connector and optionally install the Claude.ai Skill:

1. Go to Customize → Connectors → "Add custom connector"
2. Paste: https://demo.cbrowser.ai/mcp
3. Download the Claude.ai Skill (.zip) — gives Claude context about tools, pricing, and workflows
4. Go to Customize → Skills → Upload the zip

Note: The Claude.ai Skill is a lightweight knowledge file for the web interface. It is NOT the same as the Claude Code Skill (see below).

Claude Code Skill (CLI — Not for Claude.ai)

For Claude Code terminal users:

curl -fsSL https://raw.githubusercontent.com/alexandriashai/cbrowser/main/scripts/install-skill.sh | bash
npm install -g cbrowser && npx playwright install

The Claude Code Skill is a full CLI integration with workflow routing, TypeScript tools, persistent memory, and constitutional safety. See Skill Installation Guide for details.

Claude Desktop

{
  "mcpServers": {
    "cbrowser": {
      "url": "https://demo.cbrowser.ai/mcp"
    }
  }
}

Local MCP Server

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

108 MCP Tools

Category	Tools	Count
Navigation	navigate, screenshot, scroll, extract, analyze_page, find_element_by_intent	6
Interaction	click, smart_click, fill, dismiss_overlay	4
Cognitive Core	cognitive_journey_init, cognitive_journey_update_state, cognitive_journey_autonomous, cognitive_effort, cognitive_load_estimate, site_cognitive_assessment	6
Cognitive Transport	cognitive_distance, cognitive_interpolate, cognitive_coverage, transport_map	4
Attention & Visual Story	attention_analysis, attention_compare, visual_cognitive_story	3
Persona	list_cognitive_personas, compare_personas, persona_create_*, persona_questionnaire_*, persona_trait_lookup, persona_values_*	15
Testing	nl_test_inline, nl_test_file, generate_tests, repair_test, detect_flaky_tests, coverage_map	6
Visual Testing	visual_baseline, visual_regression, responsive_test, cross_browser_test, cross_browser_diff, ab_comparison	6
Site Intelligence	page_understand, site_model_query, site_model_status, site_profile_*	6
AI Friendliness	agent_ready_audit, ai_benchmark, webmcp_ready_audit, remediation_patches, llms_txt_generate, llms_txt_validate, llms_txt_diff, structured_data_suggest	8
Analysis	hunt_bugs, chaos_test, competitive_benchmark, empathy_audit	4
Performance	perf_baseline, perf_regression	2
Marketing (Enterprise)	marketing_campaign_*, marketing_audience_discover, marketing_compete, marketing_funnel_analyze, marketing_influence_matrix, marketing_lever_analysis, marketing_personas_list, list_influence_patterns	11
Security	security_audit, web_security_scan	2
Stealth (Enterprise)	stealth_enable, stealth_disable, stealth_status, stealth_check, stealth_diagnose, cloudflare_detect, cloudflare_wait	7
Session & Browser	save_session, load_session, delete_session, list_sessions, list_baselines, browser_health, browser_recover, reset_browser, heal_stats, status	10
Utility	assert, ask_user, set_api_key, api_key_status, clear_api_key, get_api_key_prompt	6

Token Cost & Selective Loading

120 MCP tools consume ~45,000 tokens in LLM context. For cost-sensitive use, load selectively:

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 };

// ~5,000 tokens instead of ~45,000
registerNavigationTools(server, context);
registerInteractionTools(server, context);
registerExtractionTools(server, context);

Categories: navigation, interaction, extraction, assertion, analysis, session, healing, visualTesting, testing, bugAnalysis, personaComparison, cognitive, cognitiveTransport, attention, siteKnowledge, values, performance, audit, browserManagement, security, marketing, remediation, llmsTxt.

---

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@v18
        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

---

API Reference

import { CBrowser } from 'cbrowser';

const browser = new CBrowser({
  headless: true,
  persistent: true,
});

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

const result = await browser.smartClick('Sign In', {
  maxRetries: 3,
  minConfidence: 0.8,
});

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

await browser.close();

Modular Imports

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';

---

Configuration

Variable	Default	Description
CBROWSER_DATA_DIR	~/.cbrowser	Data storage directory
CBROWSER_HEADLESS	true	Run headless
CBROWSER_BROWSER	chromium	Browser engine
CBROWSER_TIMEOUT	30000	Default timeout (ms)
CBROWSER_PROXY	—	Proxy URL

npx cbrowser config set-api-key  # Required for cognitive journeys

---

Enterprise Edition

CBrowser Enterprise adds:

Feature	Description
Marketing Suite	Test which design/copy/UX patterns influence which buyer segments
8 Marketing Personas	B2B (enterprise-buyer, startup-founder, procurement-manager, technical-evaluator) + Consumer (impulse-shopper, price-researcher, loyal-customer, skeptical-first-timer)
Influence Matrix	Conversion effectiveness for variant × persona combinations
Lever Analysis	Which psychological persuasion patterns work for each persona
Constitutional Stealth	Full stealth measures for authorized penetration testing
Web Security Scan	OWASP-based security scanning

All 120 MCP tools included with no rate limits.

---

License

MIT License — Free and open source. See LICENSE.

---

© 2026 Alexandria Eden · cbrowser.ai · alexandria.shai.eden@gmail.com

---

Links

• Documentation — Full docs, guides, API reference
• NPM Package
• GitHub
• Issue Tracker
• Roadmap

Research

• Research Methodology — How 26 traits were selected and validated
• Trait Index — All cognitive traits with citations
• Bibliography — Academic references
• Persona Index — All 17 cognitive + 8 marketing personas