Back to docs

Cognitive User Simulation

v16.7.0 | Autonomous, goal-driven user simulation. AI acts as a realistic persona with 26 research-backed cognitive traits.

New in v16.x: 26 cognitive traits (expanded from 12), 21 personas (expanded from 6), persona questionnaire for custom profiles, and full research documentation. See Trait-Index and Persona-Index for full reference.

Overview

Cognitive User Simulation tests how real users think and behave. It does not just test if buttons click. It tests whether an elderly first-timer can complete your signup flow.

npx cbrowser cognitive-journey \
  --persona first-timer \
  --start "https://example.com" \
  --goal "sign up for an account" \
  --vision --verbose

How It Works

┌─────────────────────────────────────────────────────────────────────┐
│                    COGNITIVE JOURNEY LOOP                            │
│                                                                      │
│  PERCEIVE → COMPREHEND → DECIDE → EXECUTE → EVALUATE → (loop)      │
│                                                                      │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐               │
│  │  Snapshot   │   │  AI thinks  │   │  Execute    │               │
│  │  the page   │──▶│  as persona │──▶│  action     │               │
│  │  (a11y tree)│   │  (Claude)   │   │  (click/fill)│              │
│  └─────────────┘   └─────────────┘   └─────────────┘               │
│         ▲                                    │                       │
│         └────────────────────────────────────┘                       │
│                      (until goal or abandon)                         │
└─────────────────────────────────────────────────────────────────────┘

The 25 Cognitive Traits

Each persona has traits organized into 6 tiers that affect how they interact with your site. See Trait-Index for complete documentation with research citations.

Tier 1: Core Processing (7 traits)

Trait Range What It Measures
patience 0-1 How quickly they give up
comprehension 0-1 Ability to understand UI conventions
workingMemory 0-1 Remembers what they've already tried
readingTendency 0-1 Scans for CTAs vs. reads everything
attentionSpan 0-1 Duration of focused attention
processingSpeed 0-1 Speed of information processing
cognitiveLoad 0-1 Current mental burden capacity

Tier 2: Emotional Response (4 traits)

Trait Range What It Measures
frustrationTolerance 0-1 Ability to handle obstacles
resilience 0-1 Emotional recovery from setbacks
anxietyLevel 0-1 Baseline anxiety affecting behavior
motivationLevel 0-1 Drive to complete tasks

Tier 3: Decision Making (4 traits)

Trait Range What It Measures
riskTolerance 0-1 Willingness to click unfamiliar elements
satisficing 0-1 Accept "good enough" vs. optimize
decisionSpeed 0-1 Speed of making choices
confirmationBias 0-1 Tendency to seek confirming evidence

Tier 4: Goal & Planning (4 traits)

Trait Range What It Measures
persistence 0-1 Tendency to retry vs. try something else
curiosity 0-1 Focused path vs. exploratory behavior
goalClarity 0-1 How well-defined their objective is
planningAbility 0-1 Capacity for strategic thinking

Tier 5: Perception (3 traits)

Trait Range What It Measures
visualAcuity 0-1 Ability to perceive visual details
changeBlindness 0-1 Failure to notice page changes
bannerBlindness 0-1 Ignoring ad-like content

Tier 6: Social & Trust (3 traits)

Trait Range What It Measures
selfEfficacy 0-1 Belief in ability to solve problems
trustCalibration 0-1 Baseline trust toward websites
socialProofSensitivity 0-1 Influenced by others' behavior

Trait Examples

elderly-user (patience: 0.9, comprehension: 0.2):

  • Very patient, keeps trying
  • Struggles with modern UI conventions
  • Reads everything thoroughly

impatient-user (patience: 0.2, riskTolerance: 0.6):

  • Gives up quickly
  • Clicks things without reading
  • Expects instant results

Built-in Personas (21)

CBrowser includes 21 research-backed personas. See Persona-Index for complete profiles with trait mappings.

General Personas (6)

Persona Description Key Traits
power-user Tech-savvy expert High comprehension, low patience
first-timer New user exploring Low comprehension, high curiosity
mobile-user Touch interface user Low patience, high satisficing
screen-reader-user Keyboard navigation High persistence, sequential attention
elderly-user Older adult (65+) High patience, low working memory
impatient-user Quick to abandon Very low patience, high FOMO

Accessibility Personas (11)

Persona Description Key Traits
motor-tremor Motor impairment Low risk tolerance, high patience
low-vision Vision impairment (magnified) High reading tendency, low change blindness
adhd Attention differences Low working memory, high curiosity, low patience
dyslexic-user Reading/text processing High patience, low reading speed
deaf-user Hearing impairment Relies on visual cues, captions
elderly-low-vision Combined age + vision High patience, needs large text
color-blind Red-green color blindness Cannot distinguish red/green UI cues
autism-spectrum Autistic adult user Needs predictability, literal interpretation, low risk tolerance
intellectual-disability Mild-moderate ID Needs plain language, image support, simple navigation
aphasia-receptive Language comprehension impairment Relies on icons and visual cues, avoids text-heavy pages
dyscalculia Numerical processing difficulty Struggles with pricing, quantities, dates, percentages

Emotional Personas (4)

Persona Description Key Traits
anxious-user High risk aversion Needs reassurance, reads warnings carefully
confident-user High self-efficacy Quick decisions, doesn't read help
emotional-user High emotional contagion Mood-driven decisions, responds to tone
stoic-user Low emotional response Methodical, unaffected by urgency cues

Attention Patterns

How different personas scan pages:

Pattern Behavior Typical Persona
targeted Looks for specific elements power-user
f-pattern Top → left side → content general users
exploratory Random exploration first-timer
sequential Tab order, keyboard nav screen-reader-user
thorough Reads everything elderly-user
skim Only large/bold elements impatient-user

Cognitive Science Foundations (v9.9.0-v10.2.0)

CBrowser's simulation is grounded in established cognitive science research:

Decision Fatigue (v9.9.0)

Based on decision fatigue research. Fatigue accumulates logarithmically with each decision.

Note: The ego depletion model (Baumeister et al., 1998) has faced replication challenges (Hagger et al., 2016 multi-lab replication). CBrowser uses a decision fatigue model focused on observable choice degradation. It does not use the contested resource depletion mechanism.

Metric Description
decisionsMade Count of choices made during journey
finalDecisionFatigue 0-1 fatigue level at end
wasChoosingDefaults True when fatigue exceeded threshold

When fatigue exceeds threshold (based on persistence trait), users start choosing defaults instead of optimal options.

Fitts' Law Mouse Timing (v9.9.0)

Classic motor control research: MT = a + b × log₂(D/W + 1)

  • D = distance to target
  • W = target width
  • Age/tremor modifiers from persona traits
  • Elderly personas show 2x+ slower mouse movements

Dual-Process Theory (v10.0.0)

Based on Kahneman (2011) System 1/2 thinking research:

System Mode When Used
System 1 Automatic, fast, intuitive Experts, familiar tasks
System 2 Deliberate, slow, analytical Novices, confusion, errors

Automatic switching:

  • → System 2 when confusion exceeds threshold OR after 3+ errors
  • → System 1 when confusion drops AND recent action succeeded

GOMS/KLM Timing (v10.0.0)

Foundational HCI research from Card, Moran & Newell:

Operator Time (ms) Description
K (keystroke) 120-500 Expert to novice typing
P (pointing) 1100 Standard mouse movement
H (homing) 400 Hand movement keyboard↔mouse
M (mental) 600-1350 Familiar to unfamiliar task prep

F-Pattern Degradation (v10.1.0)

Eye-tracking research shows scan patterns narrow under cognitive load:

Cognitive Load Effective Scan Width Visual Field
0.0-0.5 100% Full viewport
0.5-0.7 60% Narrowed to left side
0.7-0.8 30% Tunnel vision
0.8-1.0 20% Severe tunnel vision

Prospect Theory Loss Aversion (v10.1.0)

Based on Kahneman & Tversky (1979) behavioral economics research:

Frame Type Keywords Click Modifier
Loss "don't miss", "limited time", "last chance" +50% (risk-seeking)
Gain "get", "save", "earn", "free" -30% (risk-averse)

WebGazer Saliency (v10.2.0)

Visual attention priority based on eye-tracking research:

Factor Weight Description
Semantic 40% Goal relevance
Position 25% Center = high, edges = low
Contrast 20% Color contrast with background
Size 10% Size relative to viewport
Motion 5% Animation/movement

Gaze-Mouse Lag (v10.2.0)

Eyes lead mouse movements by 200-500ms depending on age:

  • Age 20: ~200ms lag
  • Age 40: ~300ms lag
  • Age 60+: ~400-500ms lag

Stress-Induced Tunnel Vision (v10.2.0)

Based on the Yerkes-Dodson Law. High arousal narrows peripheral vision:

Arousal Level Peripheral Width Peripheral Height
0.0-0.4 100% 100%
0.4-0.6 75% 80%
0.6-0.8 50% 60%
0.8-1.0 30% 40%

Banner Blindness & Habituation (v10.2.0)

Users develop blindness to repeated UI patterns:

Pattern Typical Blind After
Cookie banners 2-3 exposures
Newsletter popups 2-3 exposures
Consent dialogs 3 exposures
Promotional banners 3-4 exposures

Low comprehension users develop blindness faster (lower threshold).

Resilience & Emotional Recovery (v10.7.0)

Based on Smith et al. (2008) Brief Resilience Scale — measures ability to bounce back from setbacks:

Resilience Level Frustration Decay Recovery Speed
Low (0.0-0.3) 10% per success Frustration lingers
Medium (0.3-0.7) 20% per success Normal recovery
High (0.7-1.0) 30% per success Rapid bounce-back

Self-Efficacy Theory (v11.5.0)

Based on Bandura (1977) — belief in one's ability to solve problems:

Self-Efficacy Behavior Impact
Low (< 0.4) Abandons 40% faster on first error, blames self
Medium (0.4-0.7) Tries a few solutions, moderate confidence
High (> 0.7) Tries 3x more solution paths, persists through errors

State tracking: SelfEfficacyState with currentEfficacy, recentSuccesses, recentFailures, domainConfidence

Satisficing / Bounded Rationality (v11.5.0)

Based on Simon (1956) — accept "good enough" vs. seek optimal:

Tendency Decision Style Speed Impact
Maximizer (< 0.4) Examines all options, seeks best Slower decisions
Balanced (0.4-0.7) Evaluates key options Normal speed
Satisficer (> 0.7) Picks first acceptable option 50% faster decisions

State tracking: SatisficingState with aspirationLevel, optionsExamined, searchFatigue

Trust Calibration (v11.5.0)

Based on Fogg (2003) Stanford Persuasive Tech Lab — baseline trust toward websites:

Trust Level Behavior Impact
Low/Skeptical (< 0.4) Scrutinizes security, reads policies, 3-10x longer on CTAs
Medium (0.4-0.7) Evaluates trust signals normally
High/Trusting (> 0.7) Clicks through without reading

8 Trust Signals Detected:

  • https, security_badge, brand_recognition, professional_design
  • reviews_visible, contact_info, privacy_policy, social_proof

State tracking: TrustState with currentTrust, signalsDetected, betrayalHistory

Interrupt Recovery (v11.5.0)

Based on Mark et al. (2005) "No Task Left Behind?" — average recovery time is 23 minutes:

Recovery Ability Resumption Outcome
Low (< 0.4) Restarts from beginning, loses context
Medium (0.4-0.7) Resumes with some lost progress (10-30%)
High (> 0.7) Seamless recovery using environmental cues

Interruption Types: external, system, self_initiated, timeout

State tracking: InterruptRecoveryState with currentTaskContext, environmentalCues, interruptionLog

Abandonment Detection

The simulation automatically ends when a real user would give up:

Trigger Threshold Example
Patience depleted < 0.1 "This is taking too long"
Too confused > 0.8 for 30s "I have no idea what to do"
Too frustrated > 0.85 "This is so frustrating!"
No progress 10+ steps, < 0.1 progress "I'm not getting anywhere"
Stuck in loop Same page 3x "I keep ending up here"
Decision fatigue > threshold (v9.9.0) "I'll just pick the first option"

Vision Mode (v8.4.0)

Enable --vision to send actual screenshots to Claude:

npx cbrowser cognitive-journey \
  --persona elderly-user \
  --start "https://example.com" \
  --goal "find help page" \
  --vision

Vision mode dramatically improves accuracy for:

  • Complex layouts with multiple similar elements
  • Dropdown menus that need hover to reveal items
  • Visual cues not captured in element text
  • Pages with dynamic content

Hover-Before-Click (v8.4.0)

All clicks automatically hover parent menu triggers first:

User wants to click "International Admissions" in dropdown:

WITHOUT hover-before-click:
  → Click fails (item hidden)
  → Frustration increases
  → May abandon

WITH hover-before-click:
  → Auto-detects "Admissions" is parent
  → Hovers "Admissions" to reveal dropdown
  → Clicks "International Admissions"
  → Success!

CLI Usage

Basic Journey

npx cbrowser cognitive-journey \
  --persona first-timer \
  --start "https://example.com" \
  --goal "create an account"

With All Options

npx cbrowser cognitive-journey \
  --persona elderly-user \
  --start "https://example.com" \
  --goal "find the help page" \
  --max-steps 50 \
  --max-time 180 \
  --vision \
  --headless \
  --verbose

Options

Option Description
--persona Persona name (see built-in list)
--start Starting URL
--goal Natural language goal description
--max-steps Maximum steps before stopping (default: 30)
--max-time Maximum seconds (default: 120)
--vision Send screenshots to Claude (v8.4.0)
--headless Run without visible browser
--verbose Show detailed step-by-step output

MCP Tools

Three MCP tools for integration with Claude Desktop:

cognitive_journey_init

Initialize a journey with persona and goal:

{
  "persona": "first-timer",
  "startUrl": "https://example.com",
  "goal": "sign up for an account"
}

Returns: Cognitive profile, initial state, abandonment thresholds

cognitive_journey_update_state

Update state after taking actions:

{
  "journeyId": "journey-123",
  "actionSuccess": true,
  "currentUrl": "https://example.com/signup"
}

Returns: Updated state, abandonment check

list_cognitive_personas

List all personas with their cognitive traits.

Output Example

🎭 COGNITIVE JOURNEY
Persona: elderly-user
Goal: Find the help page
Starting: https://example.com

━━━ Step 1 ━━━
PERCEIVE: Looking at the page carefully...
I see a lot of things. There's a menu at the top...

COMPREHEND:
- Dashboard → Not sure what this means (0.2 confidence)
- "?" icon → Maybe that's help? (0.4 confidence)

DECIDE: Let me look for the word "Help" first...

[Inner monologue: "I wish they would just write 'Help' somewhere.
Why do they make everything so small?"]

━━━ Step 2 ━━━
...

━━━ JOURNEY COMPLETE ━━━
Result: SUCCESS
Time: 28.4 seconds
Steps: 3
Friction points: 1 (small "?" icon, missed on first scan)

Recommendation: Add visible "Help" text link in main navigation

Daemon Mode (v8.4.0)

For manual cognitive journeys, use daemon mode to maintain browser state:

# Start persistent session
npx cbrowser daemon start

# Run journey steps manually
npx cbrowser navigate "https://example.com"
npx cbrowser hover "Menu"           # Reveal dropdown
npx cbrowser click "Submenu Item"   # Click revealed item

# Stop when done
npx cbrowser daemon stop

Best Practices

  1. Test multiple personas - What works for power-users may fail for first-timers
  2. Use vision mode - Especially for complex UIs
  3. Check abandonment reasons - They reveal UX friction
  4. Review inner monologue - Understand user confusion
  5. Compare personas - npx cbrowser compare-personas for side-by-side

Related

Copyright: (c) 2026 Alexa Eden.

License: MIT License

Contact: [email protected]

From the Blog