# How `humanize=True` Creates Human-Like Mouse Bézier Curves in CloakBrowser

> Discover how humanize=True in CloakBrowser crafts realistic mouse movements with Bézier curves, simulating natural human hand actions for enhanced automation.

- Repository: [CloakHQ/CloakBrowser](https://github.com/CloakHQ/CloakBrowser)
- Tags: internals
- Published: 2026-05-09

---

**When `humanize=True` is passed to `launch()`, CloakBrowser patches Playwright's mouse methods to route all cursor movements through a cubic Bézier curve generator that simulates natural human hand tremors, acceleration curves, and overshoot corrections.**

CloakBrowser is an open-source automation library designed to evade bot detection by mimicking human behavior. When you enable the `humanize=True` flag during browser launch, the library intercepts every mouse action—from clicks to hovers—and replaces Playwright's instant cursor jumps with mathematically modeled Bézier paths that replicate real hand movements.

## Intercepting Playwright Actions in [`__init__.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/__init__.py)

The humanization process begins in [`cloakbrowser/human/__init__.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/human/__init__.py), where the `patch_page` function replaces native Playwright methods with specialized wrappers. According to the CloakHQ/CloakBrowser source code, this patching occurs around lines 68-94 and redirects standard mouse operations through the human-like movement layer:

- `page.click` → `_human_click`
- `page.hover` → `_human_hover`
- `page.mouse.move` → `_human_mouse_move`

These wrappers ensure that before any click or hover executes, the cursor first travels along a realistic trajectory computed by the `human_move` function.

## Cubic Bézier Generation in [`mouse.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/mouse.py)

The core algorithm resides in [`cloakbrowser/human/mouse.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/human/mouse.py). The `human_move(raw, start_x, start_y, end_x, end_y, cfg)` function constructs a **cubic Bézier curve** between coordinates, transforming linear paths into organic arcs.

### Randomized Control Points

To create natural variation, the implementation calls `_random_control_points` to generate orthogonal offsets from the straight-line trajectory. These control points introduce the subtle "wiggle" characteristic of human hand movements, ensuring no two cursor paths are identical.

### Ease-In-Out Acceleration

The progression along the curve utilizes an `_ease_in_out` cubic function rather than linear interpolation. This mimics biological motion where muscles require time to accelerate and decelerate, creating the characteristic slowing effect as the cursor approaches its target.

## Simulating Biological Imperfections

Beyond smooth curves, CloakBrowser injects specific micro-behaviors observed in real user interactions.

### Hand Tremor Simulation

The algorithm applies sinusoidal **wobble** adjustments controlled by the `mouse_wobble_max` parameter from `HumanConfig`. These tiny oscillations replicate the involuntary muscle tremors present even in steady human hands.

### Overshoot and Correction

With a probability defined by `mouse_overshoot_chance`, the cursor deliberately moves slightly past the target before settling back. This mirrors the natural correction behavior when a human overshoots a button and makes a subtle adjustment to land precisely.

### Burst Pauses

The system inserts micro-pauses during movement to simulate the brief hesitations and processing delays inherent in biological motor control, breaking the mechanical consistency of automated scripts.

## Action Flow: From Method Call to Movement

When `_human_click` executes, the wrapper follows a precise sequence defined in [`cloakbrowser/human/__init__.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/human/__init__.py) (lines 69-84):

1. Scroll the target element into view using `scroll_to_element`
2. Calculate the exact click target via `click_target`
3. Invoke `human_move` to traverse from `cursor.x, cursor.y` to `target.x, target.y` along a Bézier curve
4. Update cursor position tracking
5. Execute `human_click` through the raw mouse interface

This same pipeline applies to hover operations and their async equivalents, ensuring consistent human-like behavior across all interaction types.

## Configuration Through `HumanConfig`

Behavioral parameters are centralized in [`cloakbrowser/human/config.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/human/config.py) within the `HumanConfig` class. Key tunables include:

- `mouse_min_steps` and `mouse_max_steps`: Define the resolution of the Bézier curve interpolation
- `mouse_wobble_max`: Controls the amplitude of sinusoidal tremor injection
- `mouse_overshoot_chance`: Probability (0.0-1.0) of executing a correction movement
- Timing ranges for delays and pauses between actions

These settings enable emulation of different user personas, from rapid "default" interactions to deliberate "careful" movements.

## Implementation Examples

To enable humanized mouse movements, pass `humanize=True` when launching the browser:

```python
from cloakbrowser import launch

# Launch with human-like mouse behavior

browser = launch(headless=False, humanize=True)
page = browser.new_page()
page.goto("https://example.com")

# All subsequent actions use Bézier curves internally

page.click("#login")          # Smooth approach curve + click

page.hover("#menu")           # Natural arc to hover position

page.type("#search", "test")  # Human-like entry into input field

```

For async implementations:

```python
from cloakbrowser import launch_async

browser = await launch_async(headless=False, humanize=True)
page = await browser.new_page()
await page.goto("https://example.com")
await page.click("#login")   # Async human_move under the hood

```

## Summary

- `humanize=True` activates a patching mechanism in [`cloakbrowser/human/__init__.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/human/__init__.py) that intercepts all Playwright mouse methods
- Movement paths are calculated as cubic Bézier curves in [`cloakbrowser/human/mouse.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/human/mouse.py) using randomized control points and ease-in-out interpolation
- Realism is enhanced through configurable wobble, overshoot corrections, and burst pauses defined in `HumanConfig`
- The system preserves the standard Playwright API while replacing instantaneous movements with biologically plausible trajectories

## Frequently Asked Questions

### Which source file contains the Bézier curve mathematics?

The curve generation logic resides in [`cloakbrowser/human/mouse.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/human/mouse.py), specifically within the `human_move()` function. This file implements the cubic Bézier interpolation, control point randomization via `_random_control_points`, and easing calculations that define the cursor's trajectory.

### Can I adjust the probability of overshoot movements?

Yes. The `mouse_overshoot_chance` parameter in `HumanConfig` (defined in [`cloakbrowser/human/config.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/human/config.py)) accepts a float between 0.0 and 1.0 to control how frequently the cursor simulates overshooting and correcting its position. Higher values increase the frequency of these correction micro-movements.

### Does humanize mode affect typing speed and keyboard input?

While the primary focus of `humanize=True` is mouse movement via Bézier curves, the patching layer in [`cloakbrowser/human/__init__.py`](https://github.com/CloakHQ/CloakBrowser/blob/main/cloakbrowser/human/__init__.py) also wraps input methods. The system introduces variable delays between keystrokes in `page.type()` operations to match the irregular rhythm of human typing, though this uses timing distributions rather than spatial curves.

### What is the performance impact of calculating Bézier curves?

The overhead is minimal for typical automation tasks. The `human_move` function generates a discrete point sequence (controlled by `mouse_min_steps` and `mouse_max_steps`) and iterates through them with small delays. For most web automation scenarios, the additional 100-400ms of movement time is insignificant compared to network latency and page load times.