SimpleKeyClicker

A powerful and user-friendly GUI automation tool for simulating keyboard and mouse inputs. Built with Python and CustomTkinter for a stunning modern dark UI. Perfect for gaming macros, testing, or automating repetitive input tasks.

✨ Features

• 🎮 Game-Reliable Input: Mouse and keyboard actions are sent via PyDirectInput (SendInput / scancodes) so clicks, moves and drags register inside games
• 🎮 Action Sequencing: Create and run sequences of keyboard presses and mouse actions
• 🔁 Control Flow: repeat(N) … endrepeat blocks and ifcolor / ifnotcolor conditionals
• ☑️ Per-Action Enable/Disable: Mute any row without deleting it — great for tuning macros
• ⏱️ Customizable Timing: Set delays after each action and hold durations, plus random delay ranges (0.3-0.8)
• 🧍 Humanize Movement: Optional curved, eased, jittered mouse paths instead of instant teleports
• 🔄 Repetition Control: Run sequences indefinitely or for a specific number of times
• 📊 Live Stats: Loop/action counters, elapsed time, CPS, and an ETA + progress bar for limited runs
• ⏯️ Pause / Resume: Pause mid-sequence and resume from the same step (keeps your place)
• 🌙 Modern Dark UI: Sleek dark theme with 7 selectable accent colors and an always-on-top pin
• 🖱️ Advanced Mouse Control: Click, move and drag at specific coordinates
• 🎯 Coordinate/Color Capture: Built-in tool to capture mouse position and pixel color
• 🎨 Color Detection: Wait for / branch on specific colors at designated coordinates
• 💾 Save/Load + Auto-Restore: Export sequences as JSON, and your last session auto-restores on launch
• 🛡️ Safety Features: Safe Mode blocks dangerous keys; customizable emergency stop
• ✅ Inline Validation: Invalid timing/action fields are flagged with a red border before you run
• ⌨️ Global Hotkeys: Start, Pause, Stop and Emergency Stop — all fully customizable

📥 Download

Download the latest Windows EXE here

Or build from source (see below).

💛 Using SimpleKeyClicker? It's free and open-source, built and maintained in spare time. If it's saved you time on repetitive input tasks — or you'd like to see it keep growing — a coffee genuinely helps. See Support the Project.

🚀 Installation

Prerequisites

• Python 3.8+

Setup

1. Clone the repository:

   git clone https://github.com/timoinglin/SimpleKeyClicker.git
   cd SimpleKeyClicker

2. Create and activate virtual environment:

   python -m venv .venv
   # Windows:
   .venv\Scripts\activate
   # macOS/Linux:
   # source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Run the application:

   python main.py

🔨 Building the EXE

To create a standalone executable:

pip install pyinstaller
pyinstaller --onefile --windowed --icon=logo.ico --add-data "logo.ico;." --add-data "logo.png;." --name "SimpleKeyClicker" main.py

The EXE will be created in the dist/ folder.

📖 Quick Start

1. Click "+ Add Action" to create steps for your sequence
2. For each row:
   • Enter a Key/Button or command (see Available Actions below)
   • Use the 🎯 button to capture coordinates/colors
   • Set Hold Time (how long to hold the key/button)
   • Set Delay (pause after the action; supports ranges like 0.3-0.8)
   • Untick the checkbox to temporarily skip a row
3. Use ▲ ▼ ❏ ✕ buttons to organize rows
4. Select run mode: Indefinitely or X Times
5. Click ▶ START or press Ctrl+F2
6. ⏸ PAUSE (Ctrl+F4) to pause/resume, ⏹ STOP (Ctrl+F3) or ESC to halt

⌨️ Available Actions

Keyboard

Action	Description
a, b, 1, 2	Single key press
space, enter, tab, esc	Special keys
up, down, left, right	Arrow keys
f1 - f12	Function keys
shift, ctrl, alt, win	Modifier keys (use Hold Time)
ctrl+c, alt+f4	Key combos (modifiers held automatically)
Hello World!	Type text string

Mouse

Action	Description
click	Left click at current position
rclick	Right click at current position
mclick	Middle click at current position
click(x,y)	Left click at coordinates
rclick(x,y)	Right click at coordinates
moveto(x,y)	Move cursor to coordinates
drag(x1,y1,x2,y2)	Drag from point A to point B

Color Detection & Conditions

Action	Description
waitcolor(r,g,b,x,y)	Wait until color RGB appears at (x,y)
ifcolor(r,g,b,x,y)	Run the next row only if the color matches
ifnotcolor(r,g,b,x,y)	Run the next row only if the color is absent

Control Flow

Action	Description
repeat(N)	Repeat the rows below this marker N times…
endrepeat	…up to this marker (blocks may be nested)

Timing

Value	Description
0.5	Fixed delay in seconds
0.3-0.8	Random delay between min and max

🛡️ Safety Features

Safe Mode (On by default)

• Blocks potentially dangerous keys: alt, ctrl, shift, win, f4, delete, tab
• Toggle via the switch in the control panel

Emergency Stop

• Press ESC at any time to immediately halt automation

Global Hotkeys

Hotkey	Action
Ctrl+F2	Start automation (default)
Ctrl+F4	Pause / resume (default)
Ctrl+F3	Stop automation (default)
ESC	Emergency stop (default)

All hotkeys are fully customizable. Click ⚙ Settings in the header to open the keybind editor, then click ⏺ Record next to any hotkey and press your preferred key combination. Changes take effect immediately and are saved/loaded with your configuration files.

📦 Requirements

• Python 3.8+
• customtkinter>=5.2.0
• keyboard>=0.13.5
• PyDirectInput>=1.0.4
• pyautogui>=0.9.54
• Pillow>=10.0.0
• pynput>=1.8.1

🤝 Contributing

Contributions are welcome! Feel free to submit issues and pull requests.

💛 Support the Project

This project is free and open-source, built and maintained in spare time. If SimpleKeyClicker has saved you time — or you'd just like to see it keep growing — a coffee is hugely appreciated and helps keep this and other free tools maintained and improving.

Every contribution also funds more free open-source tools — thank you! 💛

📄 License

MIT License - Copyright (c) 2025 Timo Inglin

See LICENSE for details.

🙏 Acknowledgments

• Modern UI built with CustomTkinter
• Input simulation by PyDirectInput and PyAutoGUI
• Screen capture via Pillow (PIL)
• Global hotkeys by keyboard
• Mouse capture by pynput