HumanJS

Humanize browser automation for AI agents, QA tests, and demos.
_{Playwright that moves, types, scrolls, and reads like a real person.}

Why

Modern websites are increasingly hostile to all browser automation, and they can't tell the difference between a scraper and an AI agent acting on a user's instructions. Cloudflare, DataDome, PerimeterX read your mouse trajectory and interaction rhythm — and they block on it.

If you're building:

• AI agents that book flights, fill forms, or monitor accounts on behalf of users
• QA tests where race conditions, debounced inputs, or animation states only break at real-user pace
• Demos and walkthroughs that need to look human-paced instead of robotic
• Onboarding recordings or supervised agent monitoring

…then your robotic Playwright runs are the problem.

HumanJS makes interactions feel natural. Curved mouse paths. Typing rhythm with hesitation. Reading dwell time based on word count. Configurable personalities. Drop-in for Playwright.

What HumanJS is not

A stealth tool. We do not ship:

• ❌ Captcha solvers
• ❌ Fingerprint masking
• ❌ Proxy rotation
• ❌ "Undetectable" promises

Sophisticated anti-bot systems will still detect us. We reduce friction for legitimate use cases — and we say no to the rest by design. If you need evasion tooling, you want a stealth plugin, not HumanJS.

Install

npm install @humanjs/playwright
# or
pnpm add @humanjs/playwright

Quick start

import { chromium, createHuman } from '@humanjs/playwright';

const browser = await chromium.launch();
const page = await browser.newPage();

const human = await createHuman(page, {
  personality: 'careful',  // careful | fast | distracted | precise
  seed: 'session-42',      // deterministic for tests
  speed: 'human',          // human | fast | instant
});

await human.goto('https://example.com');
await human.click('Sign in');
await human.type('Email', '[email protected]');
await human.paste('Password', process.env.PW!);
await human.read('Welcome back');
await human.scroll('natural');

Everything that's not specified humanizes by default. Selectors prefer accessible names and roles over CSS. Determinism via seed. CI-friendly via speed: 'instant'.

Personalities

await createHuman(page, { personality: 'careful' });    // slow, precise, few mistakes
await createHuman(page, { personality: 'fast' });       // quick but still natural
await createHuman(page, { personality: 'distracted' }); // scrolls back, retypes, hovers
await createHuman(page, { personality: 'precise' });    // minimal noise, smooth motion

Extend, override, or blend:

await createHuman(page, {
  personality: { extends: 'careful', typing: { typoProbability: 0.1 } },
});

await createHuman(page, {
  personality: blend('careful', 'distracted', 0.3),
});

Or build your own and publish it as @yourname/personality-*. The full Personality type is exported and stable.

AI agent integrations

Drive a humanized browser straight from your AI agent via the MCP server — works with Claude Code, Claude Desktop, Cursor, Codex, Cline, and any other MCP client. Register it in one command:

claude mcp add humanjs -- npx -y @humanjs/mcp

…or one-click for Cursor:

Every action the agent takes goes through HumanJS without changing your agent code. See @humanjs/mcp for the full tool catalog and per-client config.

Writing HumanJS by hand with an AI coding assistant? Install the skill so Claude Code, Cursor, and Codex know the API:

npx @humanjs/skill            # this project
npx @humanjs/skill --global   # every project (~/.claude/skills, ~/.codex/AGENTS.md)

Drops the HumanJS skill into your project (.claude/skills/, .cursor/rules/, or AGENTS.md) — or, with --global, into your home dir for every project. See @humanjs/skill. (The MCP server runs a humanized browser; the skill teaches an agent to write HumanJS.)

Recorder

const recording = await human.record(async () => {
  await human.goto('/checkout');
  await human.click('Buy now');
  await human.type('Card number', '4242424242424242');
});

await recording.toVideo('checkout.mp4');          // mp4 / webm of the session
await recording.toGif('checkout.gif');            // palette-optimized gif for README embeds
await recording.toTimeline('checkout.json');      // structured JSON for analysis
await recording.toHumanJS('checkout.ts');         // runnable HumanJS script
await recording.toPlaywright('checkout.spec.ts'); // @playwright/test spec (humanized)

Or one-call for the simple case (browser/page lifecycle handled for you):

import { record } from '@humanjs/recorder';

await record({ output: 'demo.mp4' }, async (human) => {
  await human.click('a');
  await human.type('#search', 'humanjs');
});

Or use the visual generator:

npx @humanjs/generator https://your-app.com

Click through your app, pick a personality, export to clean Playwright + HumanJS.

In tests

import { test, expect } from '@playwright/test';
import { createHuman } from '@humanjs/playwright';

test('checkout flow', async ({ page }) => {
  const human = await createHuman(page, {
    personality: 'careful',
    seed: test.info().title,
    speed: process.env.CI ? 'instant' : 'human',
  });

  await human.goto('/');
  await human.click('Buy now');
  await expect(page).toHaveURL(/checkout/);
});

The seed makes runs deterministic. speed: 'instant' in CI keeps your test suite fast.

Compared to alternatives

ghost-cursor pioneered humanized mouse paths and is excellent at what it does. HumanJS is for the broader job: humanizing entire interaction sessions in Playwright, with first-class support for AI agents and QA suites.

Honest limits

• HumanJS will not defeat sophisticated bot detection (fingerprinting, TLS analysis, request patterns).
• HumanJS slows down test runs unless you use speed: 'fast' or speed: 'instant'.
• HumanJS is Playwright-first. Puppeteer support is on the roadmap, not v1.
• HumanJS does not rotate proxies, spoof fingerprints, or solve captchas. We will not add these. Open an issue and we'll close it.

Roadmap

• Mouse + scroll + typing + reading primitives
• Personalities (careful, fast, distracted, precise) + blend / extend
• Session recorder → mp4 / GIF / JSON timeline
• MCP server (@humanjs/mcp) for AI agents
• Recorder code export (Playwright / HumanJS)
• AI coding-agent skill (@humanjs/skill)
• Visual generator (@humanjs/generator)
• Plugin system + community personality authoring (@yourname/personality-*)
• Recipes (@humanjs/recipes) for common flows
• Touch / mobile humanization
• Puppeteer adapter (@humanjs/puppeteer)

Contributing

We welcome PRs that:

• Improve interaction realism
• Add primitives for new behaviors (keyboard shortcuts, drag-and-drop, right-click menus, etc.)
• Publish personalities or recipes
• Build agent adapters

We do not accept PRs that:

• Implement captcha solvers, fingerprint masking, or proxy management
• Position HumanJS as a stealth tool

See CONTRIBUTING.md.

Credits

The cubic Bezier path math behind humanized mouse trajectories is adapted from ghost-cursor by @Xetera (MIT-licensed). HumanJS humanizes a much broader surface — typing rhythm, reading dwell, scroll, the plugin system, personalities, AI-agent adapters — but the underlying coordinate generation builds on their solid foundation. See THIRD_PARTY_NOTICES.md for full attribution.

License

MIT — see LICENSE.

_{Built by Gonzalo Muñoz.}