Basic test:
`bash
whisker "Find the contact page" --url https://example.com
`

With persona:
`bash
whisker "Complete the checkout flow" \
--url http://localhost:3000 \
--persona "First-time user, not tech-savvy, age 65"
`

Custom viewport (mobile):
`bash
whisker "Navigate to settings" \
--url https://myapp.com \
--viewport 375x667
`

Limit steps:
`bash
whisker "Find pricing information" \
--url https://startup.com \
--max-steps 10
`

Authentication

For testing sites that require login, Whisker offers two approaches:

$3

Best for: Quick manual testing, 2FA, OAuth, SSO

`bash
whisker "View order history" --url https://mystore.com/account --login
`

The browser opens, you log in manually, then press Enter to let Claude take over.

$3

Best for: Repeatable tests, CI/CD pipelines

`bash


One-time: save your login session

`bash
whisker auth list # List saved auth states
whisker auth delete mysite # Delete a saved auth state
`

Auth states are stored in ~/.config/whisker/auth/ with restricted permissions.

> Note: Auth states contain session cookies which may expire. Re-save if you get logged out.

Output

Whisker generates a report with task completion status, a summary, and detailed findings organized by severity (P0-P3). Each finding includes reproduction steps, screenshot references, and suggested fixes.

`
.whisker/
├── report.md # Human-readable findings report
├── report.json # Structured JSON for automation
└── screenshots/
├── step-001.png
├── step-002.png
└── ...
`

Commands

$3

Configure your Anthropic API key interactively.

$3

Remove your stored API key.

$3

Run a usability test. This is the default command.

$3

Save browser authentication state for reuse. Opens a browser for manual login.

$3

List all saved authentication states.

$3

Delete a saved authentication state.

Configuration

$3

Whisker looks for your Anthropic API key in this order:

1. ANTHROPIC_API_KEY environment variable
2. .env.local file in current directory (for local overrides)
3. .env file in current directory
4. ~/.config/whisker/config.json (set via whisker setup)

$3

- Node.js 18+
- Anthropic API key with access to Claude's computer use capability

Programmatic Usage

`typescript
import { runSession, writeReport, WhiskerConfig } from 'whisker-ux';

const config: WhiskerConfig = {
task: "Sign up for an account",
url: "https://example.com",
maxSteps: 50,
viewport: { width: 1280, height: 800 },
outputDir: ".whisker",
// Optional auth options:
// interactiveLogin: true, // Pause for manual login
// authStateName: "mysite", // Use saved auth state
// screenshotWindow: 5, // Screenshots to keep in context
};

const { report, sessionLog } = await runSession(config);
await writeReport(report, sessionLog, config.outputDir);

console.log(Task completed: ${report.taskCompleted});
console.log(Found ${report.findings.length} issues);
`

Troubleshooting

$3

Run whisker setup or set the ANTHROPIC_API_KEY environment variable.

$3

Whisker uses Playwright's Chromium. If you encounter browser issues:

`bash
npx playwright install chromium
`

$3

If you hit API rate limits, reduce --max-steps` or wait before retrying.

$3

The browser window should appear during testing. If it doesn't, ensure you're not running in a headless environment.

License

MIT

Contributing

Issues and pull requests welcome at github.com/ericli/whisker-ux.