Virtual Crowd

AI-powered virtual user testing for Claude Code. Generate diverse personas, have them explore your app with a real headless browser, and get structured user feedback — ratings, blockers, confusions, screenshots, and actionable suggestions, just like real users.

No external test platforms. No recruiter fees. No scheduling.

Comprehensive customer feedback, Any testing objective, Instant user insights

中文文档

---

⚡ Powered by Claude Code Workflows

Virtual Crowd is built on Claude Code's Workflow engine — a brand-new orchestration feature introduced in Claude Code 2.1.154 (May 28, 2026) that can coordinate tens to hundreds of AI agents in parallel. This project is one of the first real-world applications of this cutting-edge capability.

What makes Workflows special

Capability	Description
Multi-agent orchestration	Spawn N independent AI agents, each with its own persona, goals, and browser context — all running in parallel
Structured output	Define JSON schemas (FEEDBACK_SCHEMA) that agents must return — no parsing, no guessing
Phase management	phase('Setup') → phase('Generate Personas') → phase('Browser Exploration') → phase('Report') — clean, observable pipeline
Pipeline + Parallel	pipeline() for sequential stages, parallel() for fan-out — agents explore independently, report synchronizes
Progress tracking	Live agent counts and phase progress in Claude Code's status bar via /workflows

This is not a script wrapper or a prompt template. Workflows are a first-class Claude Code primitive — Virtual Crowd leverages agent(), parallel(), pipeline(), phase(), and schema to deliver structured, reproducible user testing at scale.

Requirements

Requirement	Version	Why
Claude Code	≥ 2.1.154 (May 28, 2026)	Workflow engine with agent(), parallel(), phase(), schema
Bun	≥ 1.0	Compiles vcrowd-browse headless browser binary

Check your version: claude --version

---

🆚 Virtual Crowd vs Traditional User Testing Platforms

	Virtual Crowd	Traditional Platforms
		(UserTesting, Maze, Hotjar, etc.)
Cost	Free (uses your Claude Code session)	$20–$200+ per test
Time to results	Minutes	Hours to days
Setup	One command install	Create project, write screener, recruit
Test participants	Unlimited AI personas	5–50 paid humans
Persona diversity	Instantly generated	Limited by recruitment pool
Browser interaction	Real headless Chromium + Playwright	Real browsers (manual)
Screenshots	Auto-captured per persona	Manual or paid add-on
Custom scenarios	Free-text task description	Scripted flows only
Iteration speed	Run → read → fix → re-run in one session	Days per iteration
CI/CD integration	CLI-based, scriptable	Limited API access
Page-level tracking	Automatic (pages visited, navigation paths)	Requires analytics setup
Output format	Structured JSON, immediately actionable	Video recordings + manual tagging

Why Developers Choose Virtual Crowd

🚀 Ship Faster

"I ran 3 rounds of testing and fixed UX issues in the same afternoon — traditional platforms would still be recruiting."

💰 Zero Marginal Cost

No per-test fees. Run 4 agents or 40 — the cost is your Claude Code session.

🔄 Tight Feedback Loop

Change code → re-run test → see updated feedback. All in your terminal.

🎯 Persona Precision

Need a "non-technical small business owner" persona? Just ask. No screener surveys needed.

---

⚡ Quick Start

Requires Claude Code ≥ 2.1.154 (May 28, 2026) for Workflow support. Check with claude --version.

git clone --single-branch --depth 1 https://github.com/CoheeYang/virtual-crowd.git ~/.claude/skills/virtual-crowd
cd ~/.claude/skills/virtual-crowd && ./setup

Then in Claude Code:

/crowd-test-browser url=https://your-app.com

That's it. You'll get a structured report from 4 AI personas in minutes.

Prerequisites

• Claude Code ≥ 2.1.154 — install or update (Workflow engine required)
• Bun ≥ 1.0 (required — compiles the vcrowd-browse headless browser binary)

---

🧪 How It Works

┌─ Claude Code ──────────────────────────────────────┐
│  /crowd-test-browser url=https://myapp.com          │
│         │                                            │
│         ▼                                            │
│  ┌─ Workflow Orchestrator ──────────────────────┐    │
│  │  Phase 1: Generate 4 diverse personas        │    │
│  │  Phase 2: Launch browser daemon              │    │
│  │  Phase 3: Parallel exploration               │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐     │    │
│  │  │ Persona 1│ │ Persona 2│ │ Persona 3│ ... │    │
│  │  │ "Sarah"  │ │ "Marcus" │ │ "Yuki"   │     │    │
│  │  │ PM       │ │ Engineer │ │ Designer │     │    │
│  │  └────┬─────┘ └────┬─────┘ └────┬─────┘     │    │
│  │       │            │            │             │    │
│  │       ▼            ▼            ▼             │    │
│  │  ┌──────────────────────────────────────┐     │    │
│  │  │  vcrowd-browse (headless Chromium)   │     │    │
│  │  │  ┌────────┐ ┌────────┐ ┌────────┐   │     │    │
│  │  │  │Context 1│ │Context 2│ │Context 3│   │     │    │
│  │  │  │(cookies)│ │(cookies)│ │(cookies)│   │     │    │
│  │  │  │ Page A  │ │ Page B  │ │ Page C  │   │     │    │
│  │  │  └────────┘ └────────┘ └────────┘   │     │    │
│  │  └──────────────────────────────────────┘     │    │
│  │  Phase 4: Compile structured report          │    │
│  └───────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────┘

1. Generate Personas — Creates unique user profiles with distinct goals, pain points, and tech comfort levels
2. Explore — Each persona independently navigates the target site using a real headless browser
3. Interact — Click links, fill forms, scroll, navigate between pages
4. Capture — Screenshots, page tracking, navigation paths per persona
5. Report — Aggregated insights with ratings, blockers, confusions, and suggestions

Each persona gets an isolated browser context — independent cookies, localStorage, and session — simulating real multi-user testing.

---

📋 Parameters

Parameter	Type	Default	Description
url	string	http://localhost:3000	Target URL to test
agentCount	number	4	Number of virtual testers
personas	string[]	auto-generated	Custom persona roles
task	string	(default)	Task description for testers
enableScreenshots	boolean	true	Capture screenshots

Examples

Basic test:

/crowd-test-browser url=https://myapp.com

Custom personas:

/crowd-test-browser url=https://myapp.com personas='["Doctor", "Nurse", "Patient"]'

Focused task:

/crowd-test-browser url=https://myapp.com task='Test the signup flow. Can you create an account in under 2 minutes?'

Pre-launch check with more agents:

/crowd-test-browser url=https://staging.myapp.com agentCount=6 task='Evaluate the new dashboard feature'

---

📊 Output

The workflow returns a structured JSON report:

{
  "url": "https://myapp.com",
  "agentCount": 4,
  "insights": [
    {
      "agentName": "Sarah Chen",
      "persona": "Product Manager",
      "rating": 7,
      "completedTasks": ["Navigated to homepage", "Found pricing page"],
      "blockers": ["Signup form requires phone number"],
      "confusions": ["Pricing shows credits but no dollar amount"],
      "suggestions": ["Add pricing calculator", "Show example reports"],
      "wouldRecommend": true,
      "keyLearnings": ["Solid concept", "Needs clearer onboarding"],
      "pagesVisited": ["homepage", "pricing", "docs"],
      "screenshotPaths": ["/tmp/vcrowd-persona-0.png"]
    }
  ],
  "summary": {
    "avgRating": 7.2,
    "wouldRecommendCount": 3,
    "totalAgents": 4,
    "commonBlockers": ["signup friction"],
    "commonConfusions": ["pricing unclear"],
    "topSuggestions": ["fix broken links", "add pricing calculator"],
    "mostVisitedPages": [
      { "page": "homepage", "count": 4 },
      { "page": "pricing", "count": 3 }
    ]
  }
}

---

🌐 Built-in Browser CLI

Virtual Crowd includes vcrowd-browse, a headless browser daemon built on Bun + Playwright. Each persona gets an isolated BrowserContext — independent cookies, storage, and session.

Architecture

Subagent (persona-3)
  │  Bash: vcrowd-browse --context persona-3 goto https://example.com
  ▼
CLI (thin client)
  ├─ Read state file → port + token
  ├─ Daemon not running → auto-start
  ├─ HTTP POST {command, args, context}
  ▼
Daemon (Bun HTTP server)
  ├─ Bearer token auth
  ├─ 1 Chromium process (Playwright)
  ├─ Map<string, PersonaContext> persona isolation
  ├─ 30-min idle auto-shutdown
  ▼
Chromium (headless)
  └─ BrowserContext per persona
       ├─ Independent cookies / storage
       ├─ 1 Page per context (no multi-tab)
       └─ Independent @ref map

Commands

Command	Description
goto <url>	Navigate to URL
snapshot	Page structure with @ref labels
click @e3	Click element by ref
fill @e4 "text"	Fill form field
press Enter	Press a key
scroll down 500	Scroll the page
text	Page text content
links	List all links
screenshot <path>	Save screenshot
back	Go back
status	Daemon status
stop	Stop daemon

---

🔧 Use Cases

Pre-launch UX Audit

Run 6+ personas through your entire flow before going live. Catch navigation dead-ends, unclear CTAs, and confusing copy.

Feature Validation

Just shipped a new feature? Get immediate feedback from diverse user perspectives without waiting for real users.

Competitive Analysis

Test your competitor's site with the same personas and compare ratings side-by-side.

Landing Page Optimization

Iterate on copy, layout, and CTAs with rapid test cycles. Each run takes minutes, not days.

Accessibility Heuristics

Create personas with different ability levels to surface UX barriers.

---

🏗️ Project Structure

virtual-crowd/
├── setup                              # Installation script
├── install.sh                         # curl|bash one-liner
├── skills/
│   └── crowd-test-browser/SKILL.md    # Slash command definition
├── workflows/
│   └── virtual-crowd-test-browser.js  # Multi-agent workflow
├── browse/
│   ├── src/
│   │   ├── cli.ts                     # CLI entry point
│   │   ├── server.ts                  # HTTP daemon
│   │   ├── browser.ts                 # Playwright wrapper
│   │   ├── commands.ts                # 16 command handlers
│   │   ├── snapshot.ts                # ARIA tree + @ref system
│   │   ├── config.ts                  # State file management
│   │   └── utils.ts                   # Shared utilities
│   └── package.json                   # Bun build config
└── examples/                          # Usage examples

---

🗑️ Uninstall

# Global
rm -rf ~/.claude/skills/crowd-test-browser ~/.claude/skills/virtual-crowd
rm ~/.claude/workflows/virtual-crowd-test-browser.js

# Project-level
rm -rf .claude/skills/crowd-test-browser
rm .claude/workflows/virtual-crowd-test-browser.js

---

📄 License

MIT