bgautogui 0.1.0

Windows background mouse automation using Win32 window messages.

bgautogui

bgautogui is a small Windows-only Python package for background mouse automation using Win32 window messages.

It provides a PyAutoGUI-like API for sending click and scroll messages to windows under a screen coordinate, without moving the physical mouse cursor.

Status: alpha. This package is useful for local desktop automation and testing, but some applications may ignore posted Win32 messages.

Features

• Windows background click without moving the real cursor.
• Screen-coordinate based API: click(x, y), scroll(clicks, x, y).
• Multiple target modes: first N window candidates, specific candidate indices, or specific Win32 class names.
• Optional visual click ring for debugging coordinates.
• No required runtime dependencies outside the Python standard library.
• Optional vision extra for screenshot/image-detection workflows.

Installation

After publishing to PyPI:

pip install bgautogui

With optional vision dependencies:

pip install "bgautogui[vision]"

For local editable development:

pip install -e .

or with uv:

uv pip install -e .

Quick start

from bgautogui import BackgroundAutoGUI

bg = BackgroundAutoGUI()

# Click at the current cursor position.
bg.click()

# Click at a fixed screen coordinate.
bg.click(1500, 300)

# Scroll down at a fixed screen coordinate.
bg.scroll(-3, 1500, 300)

By default, BackgroundAutoGUI() sends each logical click to the first 4 window candidates under the coordinate.

bg = BackgroundAutoGUI(max_targets=4)

Target modes

# Default: first 4 candidates
bg = BackgroundAutoGUI()

# Only candidate 1
bg = BackgroundAutoGUI(max_targets=1)

# Specific candidate indices, 1-based
bg = BackgroundAutoGUI(target_indices=[1, 3])

# Specific Win32 class names
bg = BackgroundAutoGUI(target_classes=["IHWindowClass"])

Examples that may be useful depending on the application:

# Remote Desktop Connection input window, depending on environment.
BackgroundAutoGUI(target_classes=["IHWindowClass"])

# Chrome/Edge web content, depending on environment.
BackgroundAutoGUI(target_classes=["Chrome_RenderWidgetHostHWND"])

# Excel worksheet area, depending on environment.
BackgroundAutoGUI(target_classes=["EXCEL7"])

Visual click ring

Visual effects are disabled by default. Enable a small ring at the clicked coordinate:

bg = BackgroundAutoGUI(show_click_effect=True)
bg.click()

Enable it for a single click:

bg = BackgroundAutoGUI()
bg.click(show_click_effect=True)

Show the ring without sending any click message:

bg.showClickEffect()
bg.showClickEffect(1500, 300)

Customize the ring:

bg = BackgroundAutoGUI(
    show_click_effect=True,
    click_effect_radius=22,
    click_effect_duration=0.4,
    click_effect_color="#00AEEF",
    click_effect_width=3,
)

API overview

bg.position()
bg.size()
bg.center()
bg.virtual_screen()

bg.click()
bg.doubleClick()
bg.rightClick()
bg.middleClick()
bg.mouseDown()
bg.mouseUp()
bg.scroll()

bg.candidateWindowInfo()
bg.targetWindowInfo()
bg.windowInfo()
bg.probe()

bg.isPressed()
bg.is_mouse_button_held()

bg.set_click_effect()
bg.showClickEffect()

Inspecting candidates

from bgautogui import BackgroundAutoGUI

bg = BackgroundAutoGUI()

for info in bg.candidateWindowInfo():
    print(info.index, info.hwnd, info.class_name, info.title)

Debug by clicking each candidate one by one:

bg.probe(delay=2)

Low-interference configuration

from bgautogui import BackgroundAutoGUI

bg = BackgroundAutoGUI(
    target_indices=[1],
    show_click_effect=False,
    verbose=False,
    skip_when_mouse_button_held=True,
    hover_delay=0,
    mouse_down_up_delay=0.01,
)

Notes and limitations

bgautogui uses posted Win32 messages. A successful PostMessageW call does not guarantee that the target application will perform the UI action.

It may not work with:

• games and anti-cheat protected applications;
• some UWP/WinUI/custom-rendered applications;
• minimized windows;
• applications running as administrator when Python is not elevated;
• applications that ignore posted Win32 mouse messages.

bgautogui intentionally does not provide moveTo() or reliable background drag support. It is designed to avoid moving the physical cursor.

Responsible use

This package is intended for legitimate local desktop automation and testing. Do not use it to bypass access controls, anti-cheat systems, user consent, or software terms of service.

License

MIT License. See LICENSE.