Metadata-Version: 2.4
Name: fedora-auto-clicker
Version: 0.1.0
Summary: A small desktop auto-clicker for Fedora X11 and Wayland sessions
Author: Local
License: MIT
Classifier: Environment :: X11 Applications :: Tk
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Fedora Auto Clicker

A small, no-dependency desktop auto-clicker for Fedora. It uses the pointer's current location, starts after a configurable countdown, and supports left, right, and middle clicks.

The app defaults to 20,000 left clicks, once every 0.10 seconds, after a 3-second delay. Change the delay to any value from 0 to 60 seconds, or select **Start instantly** to skip it. Set the click count to `0` only when you intend to stop it manually.

## Two clicking modes

| Mode | How you start and stop it | Where it clicks |
| --- | --- | --- |
| Mouse position | **Hold** right for two seconds to start, **tap** right to stop. Also **Run ▸ Start mouse clicker** | Wherever the pointer already is |
| Multi click | **Hold** right and **tap** left, both to start and to stop. Also **Run ▸ Start marker clicker** | Up to ten spots you marked with rings, taken in turn |

The two are independent: each has its own trigger, its own buttons, and neither stops the other. A quick right tap can only ever *stop* the mouse-position clicker, so ordinary right-clicking around the desktop can never set anything running.

They cannot usefully run at the same time, though, and the app says so when both are going. The desktop has one pointer, and multi click has to move it onto each marker; anything the mouse-position clicker fires meanwhile lands on the marker too, not where you left the cursor.

Multi click takes three deliberate steps, in this order. Nothing earlier in the chain can happen on its own, so a stray chord out in some other application does nothing at all:

1. **Press Enable multi click.** A numbered red ring appears beside the window. The mode is on but not armed.
2. **Drag each ring onto a target and press Place markers here.** Only now is the chord live. **Add marker** gives you up to ten of them, **Remove last** takes one away, and the coordinate boxes with **Move newest** put the newest ring on an exact pixel.
3. **Hold the right mouse button and tap the left one** to start, and the same chord to stop.

With several markers the clicker takes them in turn, one per interval, so the interval stays the overall click rate rather than the rate per marker.

The rings are clipped to their own outline, so their middles are genuinely see-through and the target underneath stays visible. Turning multi click off forgets the placement, and so does adding or removing a marker, so re-arming is always deliberate. Both modes share the interval, click count, start delay, and mouse button settings.

## The countdown

Whenever a run starts on a delay, a large red disc counts the seconds down on screen so a pending run is never mistaken for a stalled one. It follows the pointer for a mouse-position run and sits on the marked spot for a multi click run. It clears itself a fraction of a second early, so it can never catch the first click. **Start instantly** skips it along with the delay.

Two things to expect from multi click:

- **The pointer parks on the target while it runs.** Wayland gives no way to read the pointer's position, so it cannot be put back between clicks. Stop the run and the mouse is yours again.
- **The rings disappear while it runs.** They are real windows, so leaving them up would mean they swallowed their own clicks.

What the right button does is decided when you let go, or after two seconds, whichever comes first:

- **Held two seconds** — starts the mouse-position clicker, the moment the two seconds pass rather than on release.
- **Tapped** — stops the mouse-position clicker. It can never start one.
- **Held with a left tap** — multi click, start or stop. However long right was held, a left tap makes the whole press a chord and nothing else.

Both need the system service below. A right press is judged when you let go: if the left button joined it at any point, however long you held right, that press was a chord. Button state is tracked per device, because a remapper such as `keyd` mirrors a mouse onto a second virtual device and every press then arrives twice; the duplicate release would otherwise read as a plain right tap.

## Run it

From this project directory:

```bash
./run.sh
```

To add it to the application launcher instead:

```bash
./install.sh
```

That also installs the mouse icon into the icon theme. The window carries the same icon itself, so the task bar shows it whether or not the launcher was installed.

No Python packages are required at runtime; the interface uses Fedora's included Tkinter.

## Fedora session support

The app selects a click backend automatically:

| Session | Backend | Requirement |
| --- | --- | --- |
| Wayland (default on current Fedora KDE/GNOME) | `ydotool` | Install it and run its system service |
| X11 | `xdotool` | Install `xdotool` (already present on many Fedora systems) |

For this Wayland session, install the backend and apply this project's one-time socket configuration:

```bash
sudo dnf install ydotool
sudo systemctl enable --now ydotool
sudo ./setup-wayland.sh
```

Then close and reopen the auto-clicker; its status should say that ydotool is ready. Fedora's stock `ydotool.service` runs as root and creates a root-only `/tmp/.ydotool_socket`. `setup-wayland.sh` installs a narrowly scoped systemd override that keeps this service socket but makes it accessible only to the current desktop user; the app explicitly directs the ydotool client to that socket.

## Mouse control service

On a Wayland desktop, a normal application cannot observe mouse input outside its own window, and it cannot place the pointer on an exact pixel. This project therefore uses a small, local system service that does both jobs. It reads only pointer devices capable of a right mouse button, ignores ydotool's virtual mouse and its own virtual pointer, and its control socket is accessible only to this desktop account.

The service reports a plain right-click and a right-plus-left chord as two separate signals, and it owns the virtual pointer used by multi click. That pointer advertises real absolute axes, which is what makes it land on the requested pixel: `ydotool mousemove -a` only imitates absolute motion with relative steps, so pointer acceleration sends it somewhere else.

Install or update this one-time control service:

```bash
sudo ./setup-right-click-stop.sh
```

Re-run it after pulling changes to `root-helper/`, since the running service keeps using the copy under `/usr/local/lib/fedora-auto-clicker`.

The app remains connected to the monitor only while its window is open. If the service is not installed, mouse-position clicking still works, but the app tells you that physical mouse control and multi click are unavailable.

`ydotool` is in Fedora's official repositories and its package includes the `ydotool.service` unit. The `ydotool click 0xC0` command used by this app emits a left-button click; `0xC1` and `0xC2` are right and middle respectively. [Fedora package details](https://packages.fedoraproject.org/pkgs/ydotool/ydotool/) [ydotool click reference](https://www.mankier.com/1/ydotool)

## Safety notes

- Leave the clicker window accessible so that you can press **Stop**.
- Holding right for two seconds starts the mouse-position clicker; a tap stops it. A tap alone can never start anything.
- The same chord that starts multi click also stops it, so you can end a run without reaching the window.
- Use a finite click count whenever possible, particularly before switching focus to another app.
- A start delay gives you time to position the pointer and focus the target window.
- The app does not bypass application permissions, login prompts, or anti-cheat systems.

## Check or test

```bash
./run.sh --check
PYTHONPATH=src:tests xvfb-run -a python3 -m unittest discover -s tests -p 'test_*.py' -v
```

The window tests build the real interface but send every click to a stand-in service, so running them never moves the pointer. `xvfb-run` keeps them off the visible desktop; without it they are skipped when no display is available.

## Project state

Created on 2026-07-28 as a self-contained scratch utility. The active Wayland session needs the documented, one-time `ydotool` service setup and the optional right-click safety service; the project does not apply administrator changes automatically.
