Skip to content

TMHSDigital/autoclicker

BranchesTags

Repository files navigation

Windows Autoclicker

Python Version Windows License Build Status Downloads Issues Pull Requests

A professional, high-performance autoclicker application for Windows with advanced automation capabilities, comprehensive safety features, and real-time performance monitoring.

Table of Contents

Features

Core Functionality

  • Precise Coordinate Targeting: Click at exact screen coordinates with pixel-perfect accuracy
  • Flexible Timing Control: Adjustable click intervals with millisecond precision
  • Multi-Button Support: Left, right, and middle mouse button options
  • Click Pattern Modes: Single click or double click with customizable patterns
  • Global Hotkey Control: Start/stop with F6/F7, emergency stop with ESC

Advanced Automation Features

  • Interactive Coordinate Picker: Click-to-select target locations with visual feedback
  • Preset Management System: Save and load coordinate presets with custom names
  • Random Variation Engine: Add realistic timing variation to avoid detection patterns
  • Burst Mode Automation: Multiple clicks with configurable pause intervals
  • Safety Control Systems: Maximum click limits and automatic time-based shutdown

Professional User Interface

  • Clean Modern GUI: Built with tkinter for native Windows integration
  • Real-time Monitoring: Live click counter, runtime display, and status indicators
  • Performance Metrics: Real-time display of clicks per second, success rate, and timing data
  • System Tray Integration: Minimize to tray for unobtrusive background operation
  • Persistent Settings: Automatic save/load of user preferences and configurations
  • Performance Controls: Toggle performance monitoring and click queuing
  • Enhanced Validation: Comprehensive input validation with user-friendly error messages

Performance Monitoring & Optimization

  • Real-time Performance Metrics: Monitor clicks per second, success rate, and average click time
  • Advanced Timing Analysis: Detailed statistics including min/max/median times and standard deviation
  • Click Queuing System: High-frequency click support with configurable queue management
  • Performance Profiling: Built-in performance monitoring with detailed operation timing
  • Resource Optimization: Efficient threading and memory management for sustained operation
  • Success Rate Tracking: Monitor operation success rates and error detection

Safety & Control Features

  • Emergency Stop System: Instant halt capability with dedicated hotkey
  • Enhanced Input Validation: Comprehensive validation with intelligent sanitization
  • Structured Error Handling: Custom exception hierarchy with user-friendly error messages
  • Screen Bounds Validation: Prevents clicks outside display boundaries
  • Activity Logging: Comprehensive logging of all click operations
  • Resource Management: Low CPU usage with optimized threading
  • Error Recovery: Graceful handling of system interruptions and validation failures

Installation

System Requirements

  • Operating System: Windows 10 or Windows 11 (64-bit recommended)
  • Python Version: Python 3.8 or higher
  • System Memory: 100 MB RAM minimum
  • Disk Space: 50 MB free space
  • Display: 1024x768 minimum resolution

Prerequisites

Installation Steps

Option 1: Direct Installation

# Clone the repository
git clone https://github.com/TMHSDigital/autoclicker.git
cd autoclicker

# Install dependencies
pip install -r requirements.txt

Option 2: Virtual Environment (Recommended)

# Clone the repository
git clone https://github.com/TMHSDigital/autoclicker.git
cd autoclicker

# Create virtual environment
python -m venv autoclicker_env

# Activate virtual environment
autoclicker_env\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Option 3: Automated Setup

# Use the provided setup script
run_autoclicker.bat

Quick Start

  1. Launch the Application

    python autoclicker.py

  2. Set Target Coordinates

    • Enter X,Y coordinates manually in the input fields
    • Or click "Pick Location" and click anywhere on screen

  3. Configure Click Settings

    • Select mouse button (Left/Right/Middle)
    • Choose click type (Single/Double)
    • Set interval timing in milliseconds

  4. Start Automation

    • Press the "Start" button or use F6 hotkey
    • Monitor progress in the status panel

  5. Stop When Complete

    • Press "Stop" button or use F7 hotkey
    • Use ESC for emergency stop

Usage

Basic Operation

Manual Coordinate Entry

  1. Enter the X coordinate in the first field
  2. Enter the Y coordinate in the second field
  3. Verify coordinates are within screen bounds

Interactive Coordinate Selection

  1. Click the "Pick Location" button
  2. The application window will minimize
  3. Click anywhere on screen to select coordinates
  4. The window will restore with selected coordinates

Advanced Configuration

Burst Mode Setup

{
  "burst_clicks": 5,
  "burst_pause": 1000
}
  • burst_clicks: Number of clicks per burst (default: 1)
  • burst_pause: Pause between bursts in milliseconds

Random Variation Configuration

{
  "interval": 1000,
  "variation": 100
}
  • interval: Base interval in milliseconds
  • variation: Random variation range (± milliseconds)

Safety Limits

{
  "max_clicks": 1000,
  "auto_stop_minutes": 30
}
  • max_clicks: Maximum clicks before auto-stop (0 = unlimited)
  • auto_stop_minutes: Auto-stop after X minutes (0 = disabled)

Performance Monitoring

Real-time Performance Metrics

The application provides comprehensive performance monitoring during operation:

  • Clicks Per Second: Real-time calculation of clicking speed
  • Success Rate: Percentage of successful clicks vs total attempts
  • Average Click Time: Mean time for each click operation
  • Performance Display: Metrics shown in the status panel during operation

Performance Controls

  • Monitor Performance: Toggle performance monitoring on/off
  • Enable Queuing: Enable click queuing for high-frequency operations
  • Queue Management: Automatic queue management with configurable size limits

Performance Tips

  • Enable queuing for operations requiring many clicks per second
  • Monitor success rate to detect clicking issues
  • Use performance metrics to optimize timing settings
  • Disable monitoring if performance overhead is unwanted

Hotkey Reference

Hotkey Function Description
F6 Start Clicking Begin automation sequence
F7 Stop Clicking End automation sequence
ESC Emergency Stop Immediate halt with cleanup
Alt+F4 Close Application Standard window close

Configuration

Settings File Structure

The application automatically creates autoclicker_settings.json:

{
  "x_coord": 100,
  "y_coord": 100,
  "interval": 1000,
  "interval_unit": "ms",
  "variation": 50,
  "mouse_button": "left",
  "click_type": "single",
  "burst_clicks": 1,
  "burst_pause": 1000,
  "max_clicks": 0,
  "auto_stop_minutes": 0,
  "presets": {
    "Game Target": {"x": 800, "y": 600},
    "Browser Click": {"x": 450, "y": 300}
  }
}

Configuration Options

Setting Type Default Description
x_coord integer 100 Target X coordinate
y_coord integer 100 Target Y coordinate
interval integer 1000 Click interval in milliseconds
interval_unit string "ms" Time unit ("ms" or "seconds")
variation integer 0 Random variation range
mouse_button string "left" Mouse button to use
click_type string "single" Click type ("single" or "double")
burst_clicks integer 1 Clicks per burst
burst_pause integer 1000 Pause between bursts (ms)
max_clicks integer 0 Maximum clicks (0 = unlimited)
auto_stop_minutes integer 0 Auto-stop timer (0 = disabled)

Safety & Compliance

Important Warnings

READ CAREFULLY BEFORE USE

Legal Compliance Requirements

Your usage must comply with:

  • Application and website terms of service
  • Local, state, and federal laws and regulations
  • Platform-specific automation policies
  • Industry-specific automation restrictions

Intended Use Cases

This tool is designed for:

  • Legitimate automation of repetitive tasks
  • Accessibility assistance and accommodation
  • Software development and testing
  • Educational and research purposes

Prohibited Activities

Do not use for:

  • Game cheating or exploitation
  • Spam generation or harassment
  • Bypassing security measures
  • Unauthorized access or control
  • Commercial use without proper licensing

Built-in Safety Features

Emergency Control Systems

  • ESC Key: Instant emergency stop with cleanup
  • Screen Bounds Checking: Prevents invalid coordinates
  • Resource Limits: Configurable click and time limits
  • Status Monitoring: Real-time operation visibility

Activity Logging

  • Comprehensive click operation logging
  • Timestamp recording for all actions
  • Error and exception tracking
  • Performance metrics collection

Technical Details

Dependencies

  • pyautogui (0.9.53+): Cross-platform GUI automation
  • keyboard (0.13.5+): Global hotkey support
  • mouse (0.7.1+): Advanced mouse event handling
  • pywin32 (227+): Windows API integration
  • Pillow (9.0.0+): Image processing and icon handling
  • pystray (0.19.4+): System tray functionality

Architecture Overview

Application Structure

autoclicker/
├── core/
│   ├── __init__.py
│   ├── settings_manager.py     # Configuration handling & validation
│   ├── click_engine.py         # Automation core with performance monitoring
│   └── exceptions.py           # Custom exception hierarchy
├── gui/
│   ├── __init__.py
│   └── main_window.py          # Enhanced GUI with performance controls
├── utils/
│   ├── __init__.py
│   └── coordinate_picker.py    # Coordinate selection & presets
├── main.py                     # Modular entry point
├── __init__.py
└── autoclicker.py              # Backward-compatible wrapper

Modular Architecture Benefits

  • Separation of Concerns: Clear boundaries between GUI, core logic, and utilities
  • Enhanced Maintainability: Focused modules with single responsibilities
  • Improved Testability: Isolated components for comprehensive testing
  • Better Error Handling: Structured exception hierarchy with user-friendly messages
  • Performance Monitoring: Built-in performance profiling and metrics collection

Threading Model

  • Main Thread: GUI event handling and user interaction
  • Click Thread: Isolated automation execution with performance monitoring
  • Queue Processor Thread: Dedicated thread for high-frequency click queuing
  • Monitor Thread: Safety monitoring and emergency response
  • Event Thread: Hotkey and system event processing

Performance Characteristics

  • CPU Usage: < 2% during normal operation, < 5% with performance monitoring
  • Memory Footprint: ~50MB resident memory
  • Click Accuracy: ±1 pixel at 60+ FPS
  • Response Time: < 10ms hotkey response
  • Performance Monitoring: Real-time metrics with minimal overhead
  • Click Queuing: Support for high-frequency operations up to 1000+ CPS
  • Thread Safety: Fully thread-safe operation with comprehensive error handling
  • Success Rate Tracking: Built-in operation reliability monitoring

Testing

The application includes comprehensive unit tests for all core functionality.

Running Tests

# Run all tests
python run_tests.py

# Run tests with coverage reporting
python run_tests.py --coverage

Test Coverage

  • Settings Manager: Validation, sanitization, and persistence testing
  • Click Engine: Performance monitoring, queuing, and error handling
  • Exception Handling: Custom exceptions and user-friendly error messages
  • Coordinate Picker: Coordinate selection and preset management
  • GUI Integration: User interface interaction and validation

Test Structure

tests/
├── test_settings_manager.py   # Configuration and validation tests
├── test_exceptions.py         # Exception handling tests
└── test_coordinate_picker.py  # Coordinate and preset tests

Performance Testing

The application includes built-in performance profiling to help optimize click operations:

  • Real-time click timing analysis
  • Success rate monitoring
  • Queue performance metrics
  • Memory usage tracking

Troubleshooting

Common Issues and Solutions

Application Startup Problems

Issue: Application fails to launch Solutions:

  • Verify Python 3.8+ installation
  • Run as administrator: right-click > Run as administrator
  • Install dependencies: pip install -r requirements.txt
  • Check Windows Event Viewer for error details

Click Registration Issues

Issue: Clicks not registering at target location Solutions:

  • Verify coordinates are within screen bounds
  • Ensure target window is active and not minimized
  • Try different click intervals (increase if too fast)
  • Check for overlay applications interfering

Hotkey Recognition Problems

Issue: Hotkeys (F6, F7, ESC) not working Solutions:

  • Run application as administrator
  • Close conflicting applications using same hotkeys
  • Restart the application
  • Check keyboard driver updates

System Tray Issues

Issue: System tray icon not appearing Solutions:

  • Verify pystray installation
  • Check Windows notification settings
  • Restart Windows Explorer
  • Run with administrator privileges

Performance Monitoring Issues

Issue: Performance metrics not displaying Solutions:

  • Ensure "Monitor Performance" is enabled in the GUI
  • Check that the application is running (metrics only show during operation)
  • Restart the application if metrics become unresponsive
  • Disable performance monitoring if experiencing performance issues

Input Validation Errors

Issue: "Validation Error" messages when starting Solutions:

  • Check that all numeric fields contain valid numbers
  • Ensure coordinates are within screen bounds
  • Verify interval values are reasonable (1ms to 1 minute)
  • Check that variation is not larger than the interval
  • Use the coordinate picker to avoid manual entry errors

Debug Mode

Enable verbose logging for troubleshooting:

python autoclicker.py --debug

Error Reporting

For persistent issues:

  1. Enable debug mode and capture output
  2. Check Windows Event Viewer (eventvwr.msc)
  3. Create an issue with full error details
  4. Include system information and reproduction steps

Contributing

We welcome contributions from the community! Here's how to get involved:

Development Setup

# Fork and clone the repository
git clone https://github.com/TMHSDigital/autoclicker.git
cd autoclicker

# Create feature branch
git checkout -b feature/your-feature-name

# Set up development environment
python -m venv dev_env
dev_env\Scripts\activate
pip install -r requirements.txt
pip install -e .  # Install in development mode

Code Standards

  • Follow PEP 8 style guidelines
  • Add docstrings for all functions and classes
  • Write comprehensive unit tests
  • Update documentation for new features
  • Ensure cross-platform compatibility

Testing Requirements

# Run comprehensive test suite
python run_tests.py

# Run tests with coverage reporting
python run_tests.py --coverage

# Run specific test modules
python -m pytest tests/test_settings_manager.py -v
python -m pytest tests/test_exceptions.py -v
python -m pytest tests/test_coordinate_picker.py -v

Pull Request Process

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes following the modular architecture:
    • Core functionality → autoclicker/core/
    • GUI components → autoclicker/gui/
    • Utilities → autoclicker/utils/
  4. Add comprehensive tests to the tests/ directory
  5. Update documentation in README.md for any new features
  6. Test thoroughly on multiple systems
  7. Submit pull request with detailed description
  8. Respond to review feedback

Areas for Contribution

  • Performance Enhancements: Improve monitoring, queuing, or timing systems
  • UI/UX Improvements: Enhance user interface design and user experience
  • Advanced Automation: Pattern recognition, conditional clicking, macro recording
  • Safety Features: Anti-detection, rate limiting, advanced validation
  • Cross-platform Support: Linux/macOS compatibility and mobile companions
  • Testing & Quality: Add tests, type hints, linting, and code quality improvements
  • Documentation: Improve guides, examples, and user help systems
  • Analytics: Performance dashboards, usage metrics, and optimization tools

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 TMHSDigital

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Support

Documentation

Community Support

Professional Support

For enterprise support, custom development, or consulting services:

Security

Report security vulnerabilities to: security@tmhsdigital.com

We follow responsible disclosure practices and will work with you to resolve any security issues.

Disclaimer

This software is provided "as is" without warranty of any kind. The authors and contributors assume no responsibility for any damages, legal issues, or consequences arising from the use or misuse of this application.

Use at your own risk and ensure compliance with all applicable laws, regulations, and terms of service.

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license

Code of conduct

Code of conduct
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages