https://github.com/alexandriashai/cbrowser
Cognitive Browser: The browser automation that thinks. Constitutional safety • Persona UX testing • Natural language interface • Self-healing selectors • Built for AI agents
https://github.com/alexandriashai/cbrowser
accessibility ai ai-testing browser-automation claude e2e-testing mcp playwright testing typescript ux-testing visual-testing web-scraping
Last synced: about 1 month ago
JSON representation
Cognitive Browser: The browser automation that thinks. Constitutional safety • Persona UX testing • Natural language interface • Self-healing selectors • Built for AI agents
- Host: GitHub
- URL: https://github.com/alexandriashai/cbrowser
- Owner: alexandriashai
- License: other
- Created: 2026-02-02T06:35:02.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-28T00:54:46.000Z (3 months ago)
- Last Synced: 2026-02-28T06:34:52.739Z (3 months ago)
- Topics: accessibility, ai, ai-testing, browser-automation, claude, e2e-testing, mcp, playwright, testing, typescript, ux-testing, visual-testing, web-scraping
- Language: TypeScript
- Homepage:
- Size: 1.98 MB
- Stars: 6
- Watchers: 1
- Forks: 1
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Threat model: THREAT_MODEL.md
- Security: SECURITY.md
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
# 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.
[](https://www.npmjs.com/package/cbrowser)
[](https://cbrowser.ai/docs)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
```bash
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:
```bash
# 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:
```bash
npx cbrowser config set-api-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](#5-minute-quickstart)
- [Cognitive Transport Chain](#cognitive-transport-chain)
- [Visual Overlays & Attention Analysis](#visual-overlays--attention-analysis)
- [AI Friendliness Suite](#ai-friendliness-suite)
- [Cognitive User Simulation](#cognitive-user-simulation)
- [Accessibility Empathy Testing](#accessibility-empathy-testing)
- [Constitutional AI Safety](#constitutional-ai-safety)
- [Site Knowledge System](#site-knowledge-system)
- [Natural Language Testing](#natural-language-testing)
- [Visual Testing](#visual-testing)
- [Competitive UX Benchmark](#competitive-ux-benchmark)
- [Geo Proxy](#geo-proxy)
- [MCP Server Integration](#mcp-server-integration)
- [CI/CD Integration](#cicd-integration)
- [API Reference](#api-reference)
- [Configuration](#configuration)
- [Enterprise Edition](#enterprise-edition)
- [Contributing](#contributing)
- [License](#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 |
```bash
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:
```bash
# 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 |
```bash
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](https://cbrowser.ai/docs/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](https://cbrowser.ai/docs/Research-Methodology) · [Trait Index](https://cbrowser.ai/docs/Trait-Index) · [Bibliography](https://cbrowser.ai/docs/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](https://cbrowser.ai/docs/Values-Framework) for full documentation.
### Custom Persona Builder
```bash
# 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:
```bash
⚠️ 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:
```bash
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
```txt
# 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"
```
```bash
npx cbrowser test-suite checkout-test.txt --html
# Auto-repair broken tests
npx cbrowser repair-tests broken-test.txt --auto-apply --verify
```
---
## Visual Testing
```bash
# 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:
```bash
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:
```bash
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](https://claude.ai/customize/connectors) → "Add custom connector"
2. Paste: `https://demo.cbrowser.ai/mcp`
3. Download the [Claude.ai Skill (.zip)](https://cbrowser.ai/downloads/cbrowser-claudeai.skill) — 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](https://claude.ai/claude-code) terminal users:
```bash
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](https://cbrowser.ai/docs/claude-skill-installation) for details.
### Claude Desktop
```json
{
"mcpServers": {
"cbrowser": {
"url": "https://demo.cbrowser.ai/mcp"
}
}
}
```
### Local MCP Server
```json
{
"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:
```typescript
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
```yaml
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
```bash
docker run --rm -v $(pwd)/tests:/work/tests ghcr.io/alexandriashai/cbrowser:latest \
test-suite tests/checkout.txt --html
```
---
## API Reference
```typescript
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
```typescript
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 |
```bash
npx cbrowser config set-api-key # Required for cognitive journeys
```
---
## Enterprise Edition
[CBrowser Enterprise](https://cbrowser.ai/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](LICENSE).
---
© 2026 Alexandria Eden · [cbrowser.ai](https://cbrowser.ai) · [alexandria.shai.eden@gmail.com](mailto:alexandria.shai.eden@gmail.com)
---
## Links
- **[Documentation](https://cbrowser.ai/docs)** — Full docs, guides, API reference
- [NPM Package](https://www.npmjs.com/package/cbrowser)
- [GitHub](https://github.com/alexandriashai/cbrowser)
- [Issue Tracker](https://github.com/alexandriashai/cbrowser/issues)
- [Roadmap](https://cbrowser.ai/docs/Roadmap)
### Research
- [Research Methodology](https://cbrowser.ai/docs/Research-Methodology) — How 26 traits were selected and validated
- [Trait Index](https://cbrowser.ai/docs/Trait-Index) — All cognitive traits with citations
- [Bibliography](https://cbrowser.ai/docs/Bibliography) — Academic references
- [Persona Index](https://cbrowser.ai/docs/Persona-Index) — All 17 cognitive + 8 marketing personas