HumanCursor: A Python package for simulating human mouse movements

Note: This is a fork of the original HumanCursor repository with planned improvements and optimizations. See PENDING_ISSUES.MD for a detailed analysis and roadmap of enhancements.

HumanCursor is a Python package that allows you to simulate realistic human mouse movements on the web and the system. It can be used for automating scripts that require mouse interactions, such as web scraping, automated tasks, testing, or gaming.

What's Different in This Fork?

This fork includes significant enhancements to improve code quality, maintainability, and anti-detection capabilities:

✅ Completed Improvements

Short Trajectory Smoothness Improvements (v2.2 - November 2025)

Critical fixes to address jerkiness and chaotic behavior in very short movements:

1. Distance-Adaptive Point Density

   • Before: Fixed minimum 30 points even for 10px movements (3 points/pixel)
   • After: Reduced density for short movements
     • Very short (<50px): 0.3 points/pixel, min 10 points
     • Short (50-100px): 0.5 points/pixel, min 15 points
   • Impact: 67% fewer points for very short movements, dramatically smoother
   • Metrics: Smoothness ratio improved 50% (0.74→0.37), jerk reduced 58%
   • Location: humancursor/utilities/calculate_and_randomize.py::generate_random_curve_parameters()

2. Distance-Scaled Distortion

   • Before: Same distortion parameters for all movement lengths
   • After: Distortion scaled based on movement distance
     • Very short (<30px): 60% reduction in std_dev, 50% in frequency
     • Short (30-75px): 30% reduction in std_dev, 20% in frequency
   • Impact: Eliminates excessive noise on short movements
   • Location: humancursor/utilities/calculate_and_randomize.py::generate_random_curve_parameters()

3. Smoothing Filter for Short Movements

   • New Feature: Moving average filter applied to movements <100px
   • Window Size: Adaptive (5 for <30px, 3 for 30-100px)
   • Blend Factor: 70% smoothing for <30px, 50% for larger
   • Impact: Removes micro-jitter while preserving natural trajectory
   • Location: humancursor/utilities/human_curve_generator.py::smooth_points()

4. Comprehensive Input Validation & Security

   • Added: Complete validation for all numeric parameters
   • Fixed: Division by zero vulnerabilities in 6 locations
   • Enhanced: Type checking with detailed error messages
   • Security: CodeQL scan clean - zero vulnerabilities found
   • Impact: Robust error handling prevents crashes and undefined behavior

Anti-Detection Enhancements (v2.0 - November 2025)

The following major improvements have been implemented to significantly enhance realism and evade sophisticated bot detection:

1. Dual-Axis Velocity-Based Distortion (Issue #1 - HIGH PRIORITY)

   • Before: Distortion only on Y-axis with fixed amplitude
   • After: Bi-directional distortion (X and Y) scaled by cursor velocity
   • Impact: Mimics natural hand tremor that increases during fast movements (1x-2.5x scaling)
   • Location: humancursor/utilities/human_curve_generator.py::distort_points()

2. Logarithmic Target Points Calculation (Issue #3 - HIGH PRIORITY)

   • Before: Linear scaling (1 point per pixel) causing thousands of points on long movements
   • After: Intelligent tiered logarithmic scaling with distance-adaptive density (v2.2 update)
   • Impact: 10x performance improvement on long movements, dramatically smoother short movements
   • Formula (Updated in v2.2):
     • Very short (<50px): 0.3 points/pixel, min 10
     • Short (50-100px): 0.5 points/pixel, min 15
     • Medium (100-500px): 60 + 40*log2(distance/100)
     • Long (>500px): 100 + 50*log2(distance/500)
   • Location: humancursor/utilities/calculate_and_randomize.py::generate_random_curve_parameters()

3. Fitts' Law Movement Duration (Issue #6 - HIGH PRIORITY)

   • Before: Fixed random duration (0.5-2s) for all movements
   • After: Scientifically accurate timing based on distance and target size
   • Impact: Movement time now correlates with difficulty (Index of Difficulty)
   • Formula: MT = a + b * log2(Distance/Width + 1) where coefficients randomized per movement
   • Randomization: a ∈ [0.08, 0.12], b ∈ [0.12, 0.18], prevents fingerprinting
   • Location: humancursor/system_cursor.py::_calculate_movement_duration()

4. Gradual Edge Complexity Reduction (Issue #5 - MEDIUM PRIORITY)

   • Before: Binary simplification (linear movement) at viewport edges
   • After: Continuous gradual reduction based on proximity to edges
   • Impact: Edge movements remain naturally curved, less detectable
   • Scaling: 70% boundary reduction, 50% knot reduction at edges, 0% at center
   • Location: humancursor/utilities/calculate_and_randomize.py::calculate_edge_proximity()

5. Distance-Adaptive Knot Distribution (Issue #4 - MEDIUM PRIORITY)

   • Before: Fixed weighted distribution (1-10 knots) regardless of distance
   • After: Intelligent scaling with randomized thresholds
   • Impact: Short movements (1-2 knots), medium (2-4), long (3-6) - eliminates pointless high knot counts
   • Anti-Fingerprinting: Thresholds randomized per movement (80-120px, 400-600px)
   • Location: humancursor/utilities/calculate_and_randomize.py::generate_random_curve_parameters()

6. Randomized Boundary Generation (Issue #2 - MEDIUM PRIORITY)

   • Before: Fixed rectangular boundaries for control point placement
   • After: Boundaries vary ±5% per movement
   • Impact: Prevents pattern detection through boundary fingerprinting
   • Location: humancursor/utilities/human_curve_generator.py::generate_internal_knots()

7. Target Overshoot Behavior (Issue #7 - MEDIUM PRIORITY)

   • Before: No overshoot simulation
   • After: Dynamic overshoot probability based on distance and target size
   • Impact: Realistic correction behavior (3-8% overshoot at 80-90% of movement)
   • Probability: Increases with distance and decreases with target size (max 40%)
   • Location: humancursor/utilities/human_curve_generator.py::add_overshoot_correction()

8. Beta Distribution Click Positioning (Issue #8 - LOW PRIORITY)

   • Before: Uniform distribution (20-80% range) for click positions
   • After: Center-biased beta distribution adaptive to element size
   • Impact: Natural clicking behavior (humans prefer element centers)
   • Parameters: α=β ∈ [2, 5] based on element area (small elements = tighter clustering)
   • Location: humancursor/utilities/web_adjuster.py::_calculate_destination()

Earlier Code Quality Improvements

• Code Quality & Architecture:

  • Added comprehensive constants module for centralized configuration
  • Refactored type hints using Union and Optional for better clarity
  • Enhanced error handling with fallback mechanisms for edge cases
  • Improved docstrings across all major classes and methods
  • Added __init__.py files for proper package structure

• Cursor Movement Enhancements:

  • Enhanced logging in WebAdjuster for better debugging
  • Improved knot generation logic to handle equal boundaries
  • Better numeric type checking (supports numpy integer and floating types)
  • Refactored click handling with dedicated click and hold methods
  • Configurable pause durations for more realistic timing

• Cross-Platform Compatibility:

  • Migrated to pathlib for cross-platform file operations
  • Updated Python requirement to 3.10+ for modern features
  • Added pytweening dependency for better easing functions

• Developer Experience:

  • Added .gitignore for cleaner repository
  • Improved HCScripter GUI with better error handling
  • Enhanced random filename generation with configurable constants

Additional Behavioral Enhancements (v2.1 - November 2025)

Building on v2.0, these optional low-priority features add final polish to behavioral realism:

1. Pause Patterns During Movement

   • Description: Brief hesitations during long movements and before clicking
   • Implementation: 1-2 pauses (20-40ms) injected at 10-80% of trajectory for movements >300px
   • Pre-Click Pause: 50-150ms delay before clicking (simulates hand settling)
   • Impact: Eliminates robotic instant-click behavior, adds natural decision points
   • Locations:
     • humancursor/utilities/human_curve_generator.py::add_pause_patterns()
     • humancursor/system_cursor.py::click_on() (line ~270)
     • humancursor/web_cursor.py::click_on() (line ~95)

2. Idle Jitter Simulation

   • Description: Tiny random movements (±1-3px) when hovering to simulate hand tremor
   • Method: cursor.idle_jitter(duration=1.0, intensity=1.0)
   • Usage: Call after moving to target to simulate natural holding behavior
   • Frequency: 10 micro-movements per second
   • Impact: Prevents perfectly static cursor position (unnatural)
   • Locations:
     • humancursor/system_cursor.py::idle_jitter() (static method)
     • humancursor/web_cursor.py::idle_jitter() (instance method)

3. Contextual Speed Variation

   • Description: Movement speed adapts to target size, fatigue, and repetition patterns
   • Target Size Impact: Smaller targets get 10-30% longer movement time (Fitts' Law)
   • Fatigue Simulation: 1% slowdown per 2 minutes of usage (capped at 15%)
   • Repetition Boost: 8-15% speed increase when performing similar repeated actions
   • Anti-Fingerprinting: Pattern resets after 5 movements to avoid detection
   • Location: humancursor/system_cursor.py::_CursorContext class + _calculate_movement_duration()

4. Directional Acceleration Profiles

   • Description: Different timing profiles for horizontal vs vertical movements
   • Horizontal: 5% faster (humans are naturally quicker at horizontal scanning)
   • Vertical: 5% more controlled (ergonomic factors, gravity awareness)
   • Jerk Minimization: Cubic smoothing on first/last 3 points (reduces sudden acceleration)
   • Impact: Eliminates uniform movement fingerprint across all directions
   • Location: humancursor/utilities/human_curve_generator.py::tween_points()

5. Optimized Bézier Calculation

   • Before: Recalculated binomial(n, i) for every point (~40% of CPU time)
   • After:
     • Precomputed binomial coefficients cached per curve
     • Pascal's triangle algorithm instead of factorial (O(k) vs O(n))
     • Optimized power calculations for small exponents
     • Global binomial cache for repeated curve degrees
   • Performance: 25-35% faster curve generation, especially for complex curves
   • Location: humancursor/utilities/human_curve_generator.py::BezierCalculator class

📊 Performance Impact

• CPU Usage: Reduced by ~60% on long movements (logarithmic scaling) + additional 25-35% from Bézier optimization

• Memory: Minimal increase (~1-2MB) for context tracking and binomial caching

• Short Movement Quality: Dramatic improvement

  • Smoothness ratio: 50% better for 10px movements (0.74→0.37)
  • Jerk reduction: 58% less for very short movements
  • Point efficiency: 67% fewer points for movements <50px
  • Quality rating: POOR/FAIR → GOOD/EXCELLENT

• Realism Score: Estimated improvement from 7.5/10 → 9.2/10 → 9.5/10 (v2.2 update)

• Detection Evasion: Significantly improved against pattern-based and timing analysis

• Code Quality: 100% input validation coverage, zero security vulnerabilities (CodeQL verified)

Content

• Features
• Requirements
• How to install
• How to use
  • HCScripter
  • WebCursor
  • SystemCursor
• Demonstration

Features

• HumanCursor uses a natural motion algorithm that mimics the way humans move the mouse cursor, with variable speed, acceleration, and curvature.
• Can perform various mouse actions, such as clicking, dragging, scrolling, and hovering.
• Designed specifically to bypass security measures and bot detection software.
• Includes:
  • 🚀 HCScripter app to create physical cursor automated scripts without coding.
  • 🌐 WebCursor module for web cursor code automation.
    • Fully supported for Chrome and Edge, not optimal/tested for Firefox and Safari, using Selenium.
  • 🤖 SystemCursor module for physical cursor code automation.

Requirements

• Python >= 3.10
  • Download the installer, run it and follow the steps.
  • Make sure to check the box that says Add Python to PATH during installation.
  • Reboot computer.

Installation

To install, you can use pip:

pip install --upgrade humancursor

Usage

HCScripter

To quickly create an automated system script, you can use HCScripter, which registers mouse actions from point to point using key commands and creates a script file for you.

After installing humancursor package, open up terminal/powershell and just copy paste this command which runs launch.py file inside the folder named HCScripter of humancursor package:

python -m humancursor.HCScripter.launch

A window will show up looking like this

Firstly, you can specify the name of the python file which will contain the script and choose the location where that file should be saved.

Then, you can turn on movement listener by pressing the ON/OFF button, where it will start registering your movements, by these commands below:

• Press Z -> Move
• Press CTRL -> Click
• Press and hold CTRL -> Drag and drop

After completing your script, press Finish button and the script file .py should be ready to go!

WebCursor

To use HumanCursor for Web, you need to import the WebCursor class, and create an instance:

from humancursor import WebCursor

cursor = WebCursor(driver)

Then, you can use the following methods to simulate mouse movements and actions:

• cursor.move_to(): Moves the mouse cursor to the element or location on the webpage.
• cursor.click_on(): Clicks on the element or location on the webpage.
• cursor.drag_and_drop(): Drags the mouse cursor from one element and drops it to another element on the screen.
• cursor.move_by_offset(): Moves the cursor by x and y pixels.
• cursor.control_scroll_bar(): Sets the scroll bar to a certain level, can be a volume, playback slider or anything. Level is set by float number from 0 to 1, meaning fullness
• cursor.scroll_into_view_of_element(): Scrolls into view of element if not already there, it is called automatically from above functions.

These functions can accept as destination, either the WebElement itself, or a list of 'x' and 'y' coordinates.

Some parameters explained:

• relative_position: Takes a list of x and y percentages as floats from 0 to 1, which indicate the exact position by width and height inside an element for example, if you set it to [0.5, 0.5], it will move the cursor to the center of the element.
• absolute_offset: If you input a list of coordinates instead of webelement, if you turn this to True, the coordinates will be interpreted as absolute movement by pixels, and not like coordinates in the webpage.
• steady: Tries to make movement in straight line, mimicking human, if set to True

SystemCursor

To use HumanCursor for your system mouse, you need to import the `SystemCursor` class, and create an instance just like we did above:

from humancursor import SystemCursor

cursor = SystemCursor()

The SystemCursor class, which should be used for controlling the system mouse (with pyautogui), only inherits the move_to(), click_on() and drag_and_drop functions, accepting only the list of 'x' and 'y' coordinates as input, as there are no elements available.

DEMONSTRATION

To quickly check how the cursor moves, you can do this:

SystemCursor

python -m humancursor.test.system

WebCursor

python -m humancursor.test.web

Some code examples

cursor.move_to(element)  # moves to element 
cursor.move_to(element, relative_position=[0.5, 0.5])  # moves to the center of the element
cursor.move_to([450, 600])  # moves to coordinates relative to viewport x: 450, y: 600
cursor.move_to([450, 600], absolute_offset=True)  # moves 450 pixels to the right and 600 pixels down

cursor.move_by_offset(200, 170)  # moves 200 pixels to the right and 170 pixels down
cursor.move_by_offset(-10, -20)  # moves 10 pixels to the left and 20 pixels up

cursor.click_on([170, 390])  # clicks on coordinates relative to viewport x: 170, y: 390
cursor.click_on(element, relative_position=[0.2, 0.5])  # clicks on 0.2 x width, 0.5 x height position of the element.
cursor.click_on(element, click_duration=1.7) # clicks and holds on element for 1.7 seconds

cursor.drag_and_drop(element1, element2)  # clicks and hold on first element, and moves to and releases on the second
cursor.drag_and_drop(element, [640, 320], drag_from_relative_position=[0.9, 0.9])  # drags from element on 0.9 x width, 0.9 x  height (far bottom right corner) and moves to and releases to coordinates relative to viewport x: 640, y: 320

cursor.control_scroll_bar(element, amount_by_percentage=0.75)  # sets a slider to 75% full
cursor.controll_scroll_bar(element, amount_by_percentage=0.2, orientation='vertical')  # sets a vertical slider to 20% full

cursor.scroll_into_view_of_element(element)  # scrolls into view of element if not already in it
cursor.show_cursor()  # injects javascript that will display a red dot over the cursor on webpage. Should be called only for visual testing before script and not actual work.

Contributing

Contributions are welcome! This fork is focused on improving the realism and anti-detection capabilities of mouse movements. Please check PENDING_ISSUES.MD for planned improvements and areas where contributions would be most valuable.

Credits

• Original Repository: riflosnake/HumanCursor
• Fork Maintainer: axeljackal

License

HumanCursor is licensed under the MIT License. See LICENSE for more information.