| Name | clickmate JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | Add your description here |
| upload_time | 2025-09-11 00:48:17 |
| maintainer | None |
| docs_url | None |
| author | ivand890 |
| requires_python | >=3.11 |
| license | MIT License Copyright (c) 2025 ivand890 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
autoclicker
clickmate
automation
macos
quartz
mouse
cli
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Clickmate
Clickmate is a macOS-friendly Python autoclicker. It prefers native Quartz CoreGraphics events on macOS (when available) and falls back to `pynput` or `pyautogui`. It features randomized delays, adjustable hold time (“pressure”), and a clean single-line status UI.
## Features
- Start/Pause with `s`
- Randomized delay per click (0.5×–1.5× of base)
- Adjust speed with `+` (faster) / `-` (slower)
- Adjust hold time with `]` (increase) / `[` (decrease)
- Toggle click engine with `m` (`pynput` → `quartz` → `pyautogui`)
- Single test click with `c`
- Optional jitter movement `j` and debug logs `d`
- Global hotkey to lock/unlock local keys: `Ctrl+Alt+K`
Defaults: delay `0.50s`, hold `0.10s`, method `quartz` (if available), jitter off.
## Install and run (uv)
Requires Python `>=3.11` and `uv`.
- Quick, no install:
```bash
uvx clickmate --help
uvx clickmate --version
uvx clickmate
```
- Install as a tool:
```bash
uv tool install clickmate
# then
clickmate
```
- From a local checkout:
```bash
# run with a fresh, isolated env and pick up local changes
uv tool run --from . --refresh clickmate
# or install locally as a tool
uv tool install .
```
Development:
```bash
uv sync
uv run clickmate --help
uv run clickmate
# or run the module entrypoint
uv run -m autoclicker --help
```
Tip: If `uv tool run --from . clickmate` doesn’t reflect local changes, add `--refresh` (above). Alternatively, bump the version in `pyproject.toml` or uninstall/reinstall the tool:
```bash
uv tool uninstall clickmate
uv tool install .
```
## Usage
1) Run the program (see above). 2) Move the mouse to your target. 3) Press `s` to start; press `s` again to pause. Use `+`/`-` to change speed and `]`/`[` to change hold time. Use `m` to switch engines when needed. Press `Ctrl+Alt+K` anytime to lock/unlock local hotkeys (safety). Exit with `Ctrl+C`.
### Hotkeys
- `s` — start/pause
- `+` / `-` — faster / slower
- `]` / `[` — increase / decrease hold time
- `m` — toggle engine (`pynput` → `quartz` → `pyautogui`)
- `c` — single test click
- `j` — toggle jitter
- `d` — toggle debug logs
- `Ctrl+Alt+K` — global lock/unlock local keys
## Status line
The app renders one continuously updated status line with fixed-width fields and a spinner while clicking.
Example:
```
▶ | delay: 0.50s | rng: 0.25–0.75 | hold: 0.10s | meth: QTZ | jitter: - | debug: - | lock: no | clicks: 000042 | last: 0.18s | next: 0.43s | cps: 3.5 | fb:1 | method quartz
```
Key fields:
- `delay` base delay; actual delays are randomized within `rng` (0.5×–1.5×)
- `hold` button press duration (“pressure”)
- `meth` engine: `QTZ` (Quartz), `PNP` (pynput), `PGA` (pyautogui)
- `lock` `yes` when local keys are locked (only `Ctrl+Alt+K` works)
- `fb:N` fallback count when switching engines was required
Notes: colors when TTY; ephemeral messages fade after ~2.5s; no extra newlines.
## macOS permissions
Grant permissions to your terminal app (Terminal/iTerm/VS Code):
1. System Settings → Privacy & Security → Accessibility → add your terminal
2. System Settings → Privacy & Security → Input Monitoring → add your terminal
3. Restart the terminal
Quartz clicks need the `Quartz` module (PyObjC). If unavailable, Clickmate automatically uses `pynput`.
## Troubleshooting
- Keys don’t work or clicks are blocked: re-check Accessibility and Input Monitoring permissions.
- App ignores clicks: press `m` to switch engines (prefer `quartz` on macOS), enable jitter `j`, or increase hold time `]` to ~0.02–0.05s.
- Output looks noisy: run in a normal terminal to get the single-line status.
## CI/CD and releases
- CI (`.github/workflows/ci.yml`): `uv sync`, `ruff`, and `pytest` on Python 3.11–3.13.
- Release (`.github/workflows/release.yml`): pushing a tag like `v1.2.3` triggers a build (`uv build --no-sources`) and publish via PyPI Trusted Publishing (OIDC). The package version is derived from the tag and injected during the build. TestPyPI publishing is not used.
## Contributing and community
- See `CONTRIBUTING.md` for development and PR guidelines.
- See `CODE_OF_CONDUCT.md` for community expectations.
- Security: see `SECURITY.md`.
## License
MIT — see `LICENSE`.
## Dependencies
- `pyautogui` — automation
- `pynput` — input handling and alternative click path
- Optional: `pyobjc` (provides `Quartz`) — enables Quartz engine on macOS
Raw data
{
"_id": null,
"home_page": null,
"name": "clickmate",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "autoclicker, clickmate, automation, macos, quartz, mouse, cli",
"author": "ivand890",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c2/00/335664ddac055256a54a8f407fd97079e311313a3d6f96f3a8212d7df3d9/clickmate-0.1.1.tar.gz",
"platform": null,
"description": "# Clickmate\n\nClickmate is a macOS-friendly Python autoclicker. It prefers native Quartz CoreGraphics events on macOS (when available) and falls back to `pynput` or `pyautogui`. It features randomized delays, adjustable hold time (\u201cpressure\u201d), and a clean single-line status UI.\n\n## Features\n\n- Start/Pause with `s`\n- Randomized delay per click (0.5\u00d7\u20131.5\u00d7 of base)\n- Adjust speed with `+` (faster) / `-` (slower)\n- Adjust hold time with `]` (increase) / `[` (decrease)\n- Toggle click engine with `m` (`pynput` \u2192 `quartz` \u2192 `pyautogui`)\n- Single test click with `c`\n- Optional jitter movement `j` and debug logs `d`\n- Global hotkey to lock/unlock local keys: `Ctrl+Alt+K`\n\nDefaults: delay `0.50s`, hold `0.10s`, method `quartz` (if available), jitter off.\n\n## Install and run (uv)\n\nRequires Python `>=3.11` and `uv`.\n\n- Quick, no install:\n ```bash\n uvx clickmate --help\n uvx clickmate --version\n uvx clickmate\n ```\n\n- Install as a tool:\n ```bash\n uv tool install clickmate\n # then\n clickmate\n ```\n\n- From a local checkout:\n ```bash\n # run with a fresh, isolated env and pick up local changes\n uv tool run --from . --refresh clickmate\n # or install locally as a tool\n uv tool install .\n ```\n\nDevelopment:\n```bash\nuv sync\nuv run clickmate --help\nuv run clickmate\n# or run the module entrypoint\nuv run -m autoclicker --help\n```\n\nTip: If `uv tool run --from . clickmate` doesn\u2019t reflect local changes, add `--refresh` (above). Alternatively, bump the version in `pyproject.toml` or uninstall/reinstall the tool:\n```bash\nuv tool uninstall clickmate\nuv tool install .\n```\n\n## Usage\n\n1) Run the program (see above). 2) Move the mouse to your target. 3) Press `s` to start; press `s` again to pause. Use `+`/`-` to change speed and `]`/`[` to change hold time. Use `m` to switch engines when needed. Press `Ctrl+Alt+K` anytime to lock/unlock local hotkeys (safety). Exit with `Ctrl+C`.\n\n### Hotkeys\n\n- `s` \u2014 start/pause\n- `+` / `-` \u2014 faster / slower\n- `]` / `[` \u2014 increase / decrease hold time\n- `m` \u2014 toggle engine (`pynput` \u2192 `quartz` \u2192 `pyautogui`)\n- `c` \u2014 single test click\n- `j` \u2014 toggle jitter\n- `d` \u2014 toggle debug logs\n- `Ctrl+Alt+K` \u2014 global lock/unlock local keys\n\n## Status line\n\nThe app renders one continuously updated status line with fixed-width fields and a spinner while clicking.\n\nExample:\n```\n\u25b6 | delay: 0.50s | rng: 0.25\u20130.75 | hold: 0.10s | meth: QTZ | jitter: - | debug: - | lock: no | clicks: 000042 | last: 0.18s | next: 0.43s | cps: 3.5 | fb:1 | method quartz\n```\n\nKey fields:\n- `delay` base delay; actual delays are randomized within `rng` (0.5\u00d7\u20131.5\u00d7)\n- `hold` button press duration (\u201cpressure\u201d)\n- `meth` engine: `QTZ` (Quartz), `PNP` (pynput), `PGA` (pyautogui)\n- `lock` `yes` when local keys are locked (only `Ctrl+Alt+K` works)\n- `fb:N` fallback count when switching engines was required\n\nNotes: colors when TTY; ephemeral messages fade after ~2.5s; no extra newlines.\n\n## macOS permissions\n\nGrant permissions to your terminal app (Terminal/iTerm/VS Code):\n1. System Settings \u2192 Privacy & Security \u2192 Accessibility \u2192 add your terminal\n2. System Settings \u2192 Privacy & Security \u2192 Input Monitoring \u2192 add your terminal\n3. Restart the terminal\n\nQuartz clicks need the `Quartz` module (PyObjC). If unavailable, Clickmate automatically uses `pynput`.\n\n## Troubleshooting\n\n- Keys don\u2019t work or clicks are blocked: re-check Accessibility and Input Monitoring permissions.\n- App ignores clicks: press `m` to switch engines (prefer `quartz` on macOS), enable jitter `j`, or increase hold time `]` to ~0.02\u20130.05s.\n- Output looks noisy: run in a normal terminal to get the single-line status.\n\n## CI/CD and releases\n\n- CI (`.github/workflows/ci.yml`): `uv sync`, `ruff`, and `pytest` on Python 3.11\u20133.13.\n- Release (`.github/workflows/release.yml`): pushing a tag like `v1.2.3` triggers a build (`uv build --no-sources`) and publish via PyPI Trusted Publishing (OIDC). The package version is derived from the tag and injected during the build. TestPyPI publishing is not used.\n\n## Contributing and community\n\n- See `CONTRIBUTING.md` for development and PR guidelines.\n- See `CODE_OF_CONDUCT.md` for community expectations.\n- Security: see `SECURITY.md`.\n\n## License\n\nMIT \u2014 see `LICENSE`.\n\n## Dependencies\n\n- `pyautogui` \u2014 automation\n- `pynput` \u2014 input handling and alternative click path\n- Optional: `pyobjc` (provides `Quartz`) \u2014 enables Quartz engine on macOS",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2025 ivand890 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "Add your description here",
"version": "0.1.1",
"project_urls": {
"Changelog": "https://github.com/ivand890/autoclicker/releases",
"Homepage": "https://github.com/ivand890/autoclicker",
"Issues": "https://github.com/ivand890/autoclicker/issues",
"Repository": "https://github.com/ivand890/autoclicker"
},
"split_keywords": [
"autoclicker",
" clickmate",
" automation",
" macos",
" quartz",
" mouse",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a878625cd2bce4e377dc47e3ead0def21802dbd71170735c7315f0171ecd4325",
"md5": "b3f141cc08580769075cef271d782255",
"sha256": "b6292b2b9b9435d0fe3740ba7a83b920315fbe0a3467d51319133248da8b285d"
},
"downloads": -1,
"filename": "clickmate-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b3f141cc08580769075cef271d782255",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 10712,
"upload_time": "2025-09-11T00:48:16",
"upload_time_iso_8601": "2025-09-11T00:48:16.893630Z",
"url": "https://files.pythonhosted.org/packages/a8/78/625cd2bce4e377dc47e3ead0def21802dbd71170735c7315f0171ecd4325/clickmate-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c200335664ddac055256a54a8f407fd97079e311313a3d6f96f3a8212d7df3d9",
"md5": "217affd00788d3dedd02357568e53981",
"sha256": "a06b4d29f84be599344bb3e025521cfb493c070d698802b778af6f01c6cdfe8a"
},
"downloads": -1,
"filename": "clickmate-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "217affd00788d3dedd02357568e53981",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 9432,
"upload_time": "2025-09-11T00:48:17",
"upload_time_iso_8601": "2025-09-11T00:48:17.652472Z",
"url": "https://files.pythonhosted.org/packages/c2/00/335664ddac055256a54a8f407fd97079e311313a3d6f96f3a8212d7df3d9/clickmate-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 00:48:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ivand890",
"github_project": "autoclicker",
"github_not_found": true,
"lcname": "clickmate"
}
