User Testing Agent

AI-powered usability testing that simulates real users navigating your web app. Define a persona (who), give it a task (what), and get a detailed usability report showing where they got stuck, confused, or gave up.

Built on Claude Code with browser automation — the agent actually sees and clicks through your app like a human would.

How It Works

1. You define personas — behavioral profiles grounded in UX research (impatient clicker, careful reader, etc.)
2. You define tasks — things a real user would try to do ("create a new project", "find the billing page")
3. The agent opens your app in Chrome, navigates as that persona, and produces a report with usability findings, severity ratings, and screenshots

Each persona has configurable traits like reading depth, patience budget, error recovery style, and exploration strategy. These shape how the agent actually behaves — an impatient user will give up after 15 actions, a careful one will read every label and try 35+ approaches.

Quick Start

Prerequisites

This tool works best with a Claude Code subscription (Max or Pro plan) since the Chrome extension requires signing into your Claude account. You'll use the same account for both Claude Code in the terminal and the Chrome extension.

You'll need these set up before running the setup script:

1. macOS (Linux support coming)

2. Python 3.11+ — check with python3 --version

3. Chrome browser

4. Claude Code — install and sign in:

   npm install -g @anthropic-ai/claude-code
   claude    # follow the prompts to sign in with your Claude account

   Full instructions: Claude Code docs

5. Claude Code Chrome extension — this is what lets the agent see and control your browser:

   1. Install the Claude Code Chrome extension from the Chrome Web Store
   2. Click the extension icon in Chrome and sign in with the same Claude account you used for Claude Code
   3. Complete the onboarding flow and accept any permissions popups
   4. Run claude --chrome in your terminal to test the connection

   Troubleshooting the Chrome connection (it rarely connects perfectly the first time):

   • If you get "No browser responded" — click the extension icon in Chrome, close and reopen the panel, and accept any permissions popups that appear
   • If you get "Multiple Chrome extensions connected" — open the extension panel in the specific Chrome browser/profile you want to use and click "Connect"
   • If the extension panel seems stuck — close it, wait a moment, reopen it
   • As a last resort, fully quit and reopen Chrome

   The connection is finicky during first-time setup but works reliably once established. See the Chrome integration docs for more details.

Setup

git clone https://github.com/your-username/user-testing-agent.git
cd user-testing-agent
./setup.sh

Then launch Claude Code and run the interactive setup:

claude
# Inside Claude Code, type:
/setup

The setup wizard will ask for your app URL, help you pick a persona, and create your first task. Takes about 2 minutes.

Run a Test

1. Open Chrome and log into your app (the agent doesn't handle authentication)
2. Navigate to your starting page
3. Start Claude Code with Chrome connected:

claude --chrome

4. Invoke the test agent by typing @user-tester in your prompt
5. Type /run-test — it will ask you to pick a persona and task
6. Watch it navigate your app, then check runs/ for the report

Alternatively, you can launch the agent directly in a new terminal:

claude --chrome --agent user-tester

CLI Alternative

# List what's available
ux-test list personas
ux-test list tasks

# Run a test
ux-test run --persona impatient-new-user --task my-task --url https://app.example.com/dashboard

Persona Traits

Each trait is grounded in real UX research:

Trait	Options	Based On
search_vs_browse	search-first / browse-first / mixed	Perfetti & Spool
reading_depth	reads / scans / glances	Nielsen F-pattern
exploration_strategy	breadth-first / depth-first / linear	Masson et al.
scent_threshold	low / high	Information Foraging Theory
cognitive_effort	high / low	Need for Cognition
error_recovery	retries / backtracks / abandons	Reason's taxonomy
persistence	high / medium / low	Computer Self-Efficacy
patience_budget	integer (clicks before giving up)	—

Creating Personas and Tasks

Use the interactive skills:

• /create-persona — walks you through each trait with plain-language explanations
• /create-task — helps define what the user should try to accomplish

Or edit the YAML files directly in personas/ and tasks/.

Project Structure

personas/           Persona YAML definitions
tasks/              Task YAML definitions
runs/               Test output (reports, screenshots, SQLite databases)
scripts/            Hook scripts for logging and patience tracking
ux_agent/           Python package (CLI, orchestrator, hooks, reporting)
examples/redo/      Example personas and tasks from original development

Example Output

Each test run produces:

• Markdown report — usability findings with severity ratings
• JSON report — structured data for integration with other tools
• SQLite database — full action log with timestamps

Requirements

The agent needs an active Chrome session where you're already logged into your app. It does not handle authentication — you log in, it takes over from there.

License

MIT