Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/tmhsdigital/autoclicker


https://github.com/tmhsdigital/autoclicker

Last synced: 14 days ago
JSON representation

Awesome Lists containing this project

README 

          
# Windows Autoclicker



[![CI](https://github.com/TMHSDigital/autoclicker/actions/workflows/ci.yml/badge.svg)](https://github.com/TMHSDigital/autoclicker/actions/workflows/ci.yml)

[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)

[![Windows](https://img.shields.io/badge/Windows-10+-0078D4.svg)](https://www.microsoft.com/windows/)

[![License](https://img.shields.io/badge/license-CC_BY--NC_4.0-green.svg)](LICENSE)



A configurable autoclicker for Windows with coordinate targeting, burst mode, preset management, and safety controls.



## Table of Contents



- [Features](#features)

- [Installation](#installation)

- [Quick Start](#quick-start)

- [Usage](#usage)

- [Configuration](#configuration)

- [Safety & Compliance](#safety--compliance)

- [Technical Details](#technical-details)

- [Testing](#testing)

- [Troubleshooting](#troubleshooting)

- [Contributing](#contributing)

- [License](#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 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



### User Interface

- **Native GUI**: Built with tkinter for Windows integration

- **Live Status**: Click counter, runtime display, and status indicators

- **System Tray Integration**: Minimize to tray 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](https://python.org/downloads/))

- Windows 10/11 with administrator privileges for full functionality



### Installation Steps



#### Option 1: Direct Installation

```bash

# 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)

```bash

# 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

```bash

# Use the provided setup script

run_autoclicker.bat

```



## Quick Start



1. **Launch the Application**

   ```bash

   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

```json

{

  "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

```json

{

  "interval": 1000,

  "variation": 100

}

```

- **interval**: Base interval in milliseconds

- **variation**: Random variation range (± milliseconds)



#### Safety Limits

```json

{

  "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 with cleanup |

| Alt+F4 | Close Application | Standard window close |



## Configuration



### Settings File Structure

The application automatically creates `autoclicker_settings.json`:



```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



#### 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



### Architecture Overview



#### Application Structure

```

autoclicker.py

autoclicker/

├── main.py

├── app/                  # controller, hotkeys, tray

├── gui/                  # main_window + sections/

├── core/                 # engine, settings, safety, session_log

└── utils/

    └── coordinate_picker.py

```



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



#### Threading Model

- **Main Thread**: GUI event handling and user interaction

- **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

```bash

# 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; coverage gate on click engine)

- `test_exceptions.py`, `test_safety.py`, `test_audit_regressions.py`

- `test_coordinate_picker.py`



## 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](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:



```bash

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**: 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 **Creative Commons Attribution-NonCommercial 4.0 International License** (CC BY-NC 4.0). See the [LICENSE](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.



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