ClickForMe

Lightweight Windows desktop utility for recording, editing, saving, loading, and replaying mouse click workflows.

ClickForMe is designed as a practical open-source productivity tool for simple repetitive desktop tasks. It focuses on clear controls, screen-aware playback, editable timing, and a modular Python codebase that is structured for packaging as a Windows executable.

Repository: github.com/suspiriaa/ClickForMe

Current package version: 0.1.0

Screenshot

Demo

Recording and Playback

Language Switching

Features

• Global hotkeys for starting, stopping, replaying, and clearing recordings
• Mouse click recording with per-step timing
• Mouse button-aware recording and playback for left, right, middle, and side buttons
• Mouse wheel scroll up/down recording and playback
• Basic single-key keyboard recording and playback
• Input backend architecture prepared for Windows, macOS, and Linux platform adapters
• Windows backend now includes an additional low-level XBUTTON hook attempt for side mouse buttons
• Editable delay values between recorded actions
• Save and load recordings with a custom .cfm.json format
• Validation for malformed .cfm.json files with clearer load errors
• Resolution-aware playback using proportional coordinates
• Multi-monitor-aware action handling
• Optional human-like click variation for less rigid movement
• Built-in multi-language UI support with a translation catalog
• Lightweight Tkinter-based desktop interface

Installation

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

For local development and tests:

.\.venv\Scripts\python.exe -m pip install -e .[dev]

Run the app with the thin launcher in app.py.

Usage

.\.venv\Scripts\python.exe app.py

Default hotkeys:

• F6 starts recording
• F7 stops recording
• F8 starts or stops playback
• F9 clears the current recording
• F10 pauses or resumes playback

On Windows, the input inspector can also surface keyboard-style fallback events such as key:f13 when a mouse vendor tool maps extra buttons to keyboard keys instead of native mouse buttons. Vendor-specific HID-only mouse buttons are still not guaranteed until a raw input layer is added.

Tests

Run the current regression checks with:

.\.venv\Scripts\python.exe -m pytest

Automated coverage includes serializer round-trips, payload validation, proportional coordinate resolution, player behavior, recorder behavior, and translation completeness.

Project Structure

ClickForMe/
|-- app.py
|-- CHANGELOG.md
|-- pyproject.toml
|-- requirements.txt
|-- LICENSE
|-- README.md
|-- .github/
|   |-- workflows/
|   |   `-- ci.yml
|-- docs/
|   |-- localization.md
|   |-- roadmap.md
|   |-- release-checklist.md
|   |-- release-notes-v0.1.0.md
|   `-- smoke-test.md
|-- screenshots/
|   |-- click.gif
|   |-- lang.gif
|   `-- ss-1.png
|-- logos/
|-- tests/
`-- src/
    |-- clickforme/
        |-- __init__.py
        |-- i18n.py
        |-- input_backends/
        |   |-- __init__.py
        |   |-- base.py
        |   |-- factory.py
        |   |-- generic_pynput.py
        |   |-- linux.py
        |   |-- macos.py
        |   `-- windows.py
        |-- main.py
        |-- models.py
        |-- mouse_buttons.py
        |-- player.py
        |-- recorder.py
        |-- screen_utils.py
        |-- serializer.py
        |-- ui_actions.py
        |-- ui_selection.py
        |-- ui_storage.py
        `-- ui.py

Module Layout

• models.py: shared recording and monitor data structures
• mouse_buttons.py: mouse button normalization and display helpers
• recorder.py: mouse recording flow and event capture
• player.py: playback scheduling and click execution
• serializer.py: save and load support for .cfm.json
• screen_utils.py: monitor detection and coordinate conversion
• i18n.py: translation catalog, language options, and UI copy helpers
• input_backends/base.py: shared backend protocol and normalized click event model
• input_backends/factory.py: runtime backend selection by platform
• input_backends/generic_pynput.py: cross-platform fallback backend
• input_backends/windows.py: Windows-specific input backend
• input_backends/macos.py: macOS input backend
• input_backends/linux.py: Linux input backend
• ui_actions.py: shared button and hotkey action definitions for the desktop UI
• ui_selection.py: selection text and action-editing helpers for the recording list
• ui_storage.py: save/load helpers that bridge UI flows with serializer validation
• ui.py: desktop interface orchestration
• main.py: package entry point

Roadmap

See docs/roadmap.md for current priorities and next-stage improvements. See docs/smoke-test.md for release-oriented manual test coverage, docs/localization.md for translation maintenance, docs/release-checklist.md for first-release prep, and CHANGELOG.md for release history.

Responsible Use

ClickForMe is intended for legitimate desktop workflow automation and repetitive productivity tasks.

• Use it only on systems and workflows you control or are authorized to automate.
• Do not position or distribute it as a cheating, stealth, or malicious utility.
• Review your local rules, platform policies, or workplace requirements before using automation tools.

Support

If you would like to support ongoing development, you can follow the project on Patreon.

License

This repository uses the MIT License. See LICENSE.