Windows Autoclicker

A fast, configurable autoclicker for Windows with a modern light/dark interface, precise coordinate targeting, burst mode, presets, and built-in safety controls.

Highlights

• Pixel-precise clicking at a fixed point, with single/double and left/right/middle support
• Click-to-pick coordinate selection and named presets
• Burst mode and randomized timing variation to vary cadence
• Safety first: failsafe on by default, optional click/time limits, runaway-speed guard, fail-closed pause-when-unfocused
• Global hotkeys (F6/F7/ESC), system tray, settings in %APPDATA%\WindowsAutoclicker
• Modern themed UI with a one-click light/dark toggle

Table of Contents

• Features
• Installation
• Quick Start
• Usage
• Configuration
• Safety & Compliance
• Technical Details
• Testing
• Troubleshooting
• Contributing
• License

---

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, load, and delete named coordinate presets
• Random Variation Engine: Optional jitter around the click interval for a less metronomic cadence
• Burst Mode Automation: Multiple clicks with configurable pause intervals
• Safety Control Systems: Maximum click limits and automatic time-based shutdown

User Interface

• Modern Themed GUI: tkinter with the Sun Valley (sv-ttk) theme and a light/dark toggle (remembered between sessions)
• Minimal by Default: Burst, safety limits, and advanced toggles tuck into a collapsible "Advanced" section
• Compact Status Bar: Colored state indicator with inline click counter, runtime, and performance
• System Tray Integration: Minimize to tray (using the app icon) for background operation
• Persistent Settings: Automatic save/load of user preferences
• Input Validation: Comprehensive validation with user-friendly error messages

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
• Session logging: Append-only log under %APPDATA%/WindowsAutoclicker/sessions.log (start/stop/safety events)
• 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.10 or higher
• System Memory: 100 MB RAM minimum
• Disk Space: 50 MB free space
• Display: 1024x768 minimum resolution

Prerequisites

• Python 3.10+ (Download from python.org)
• Windows 10/11 with administrator privileges for full functionality

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 .venv

# Activate virtual environment
.venv\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
   • Expand Advanced for burst mode, safety limits, and failsafe toggles

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)

Hotkey Reference

Hotkey	Function	Description
F6	Start Clicking	Begin automation sequence
F7	Stop Clicking	End automation sequence
ESC	Emergency Stop	Immediate halt (cancels coordinate pick if picking)
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,
  "theme": "light",
  "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)
theme	string	"light"	UI theme ("light" or "dark")

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 (or cancel Pick Location)
• PyAutoGUI failsafe: On by default; moving the mouse to a screen corner aborts clicking
• Pause when unfocused: Optional; refuses to start if the foreground window cannot be read
• Screen Bounds Checking: Prevents invalid coordinates
• Resource Limits: Configurable click and time limits plus a runaway CPS ceiling
• Status Monitoring: Real-time operation visibility

Session log

• Append-only log in %APPDATA%/WindowsAutoclicker/sessions.log
• Records start, stop reason, click count, and coordinates (no secrets)

Technical Details

Dependencies

• pyautogui (0.9.53+): GUI automation (Windows target)
• 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
• sv-ttk (2.6.0+): Sun Valley ttk theme (light/dark UI)

Architecture Overview

Application Structure

autoclicker.py
autoclicker/
├── main.py
├── app/                  # controller, hotkeys, tray
├── gui/                  # main_window + sections/ (incl. collapsible.py, advanced.py)
├── core/                 # engine, settings, safety, session_log
└── utils/
    └── coordinate_picker.py

Settings file: %APPDATA%/WindowsAutoclicker/autoclicker_settings.json (legacy CWD file migrated once). See docs/ARCHITECTURE.md.

Threading Model

• Main Thread: GUI event handling; worker callbacks marshaled with root.after
• Click Thread: Isolated automation execution
• Queue Processor Thread: Optional thread for high-frequency click queuing

Design Notes

• Threaded click loop keeps the GUI responsive
• Click queuing available for high-frequency operations
• Daemon threads ensure clean exit on window close

Testing

The application includes comprehensive unit tests for all core functionality.

Running Tests

# Run all unit tests (pytest)
python run_tests.py

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

# Smoke check: dependencies and project layout (not part of pytest)
python scripts/smoke_check.py

Test modules

• test_settings_manager.py, test_settings_migration.py
• test_click_engine.py (mocked pyautogui)
• test_exceptions.py, test_safety.py, test_audit_regressions.py
• test_coordinate_picker.py, test_gui_callbacks.py, test_controller.py
• Coverage gate: autoclicker package, --cov-fail-under=65

Troubleshooting

Common Issues and Solutions

Application Startup Problems

Issue: Application fails to launch Solutions:

• Verify Python 3.10+ 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

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

Error Reporting

For persistent issues:

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

Contributing

See CONTRIBUTING.md for setup (make install or tasks.bat install), tests, lint, pre-commit, licensing (CC BY-NC 4.0), and the tag-based release flow.

Quick start:

tasks.bat install
tasks.bat check

CI and maintainers use pinned dependencies in requirements-lock.txt (regenerate with tasks.bat lock on Python 3.11).

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: Failsafe default-on, rate limiting, input 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 Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0). See the LICENSE file for details.

You are free to share and adapt this software for non-commercial purposes, with appropriate attribution. For commercial licensing inquiries, contact TM Hospitality Strategies.

---

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.

Automation tools can be abused. Use only on systems and software you are authorized to control.

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