Metadata-Version: 2.4
Name: keyhac
Version: 2.0.0
Summary: Keyhac 2 - Python-scriptable keyboard customization tool for Windows and macOS
Author: craftware
License-Expression: MIT
Project-URL: Homepage, https://github.com/crftwr/keyhac2
Project-URL: Repository, https://github.com/crftwr/keyhac2
Project-URL: Issues, https://github.com/crftwr/keyhac2/issues
Keywords: keyboard,hotkey,keymap,macro,remap,customization
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: MacOS X
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: puikit>=1.0.8
Requires-Dist: pyobjc-framework-Cocoa>=10; sys_platform == "darwin"
Requires-Dist: pyobjc-framework-Quartz>=10; sys_platform == "darwin"
Requires-Dist: pyobjc-framework-ApplicationServices>=10; sys_platform == "darwin"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# Keyhac 2

Python-scriptable keyboard customization for **Windows and macOS**.

Keyhac installs a system-wide keyboard hook and lets you script what your keys do in
Python. You write one file, `~/.keyhac/config.py`, and it runs unchanged on both OSes —
remapping keys, binding keys to Python functions, and driving windows, applications and
the clipboard from the keyboard.

Keyhac 2 is the successor to both
[Keyhac for Windows](https://github.com/crftwr/keyhac) and
[Keyhac for macOS](https://github.com/crftwr/keyhac-mac), rebuilt as one shared codebase.
Its UI is built on [PuiKit](https://github.com/crftwr/puikit).

## Features

- **Key remapping**: key → key, key → key sequence, key → Python function.
- **Per-application key tables**: match by app name, window title, Win32 window class,
  or the full accessibility focus path (AX on macOS, UI Automation on Windows) — down to
  "only in this app's text editor pane".
- **User modifiers**: turn any key into a modifier of your own (User0–User3), invisible
  to applications.
- **One-shot modifiers**: tap a modifier alone for one action, hold it to modify.
- **Multi-stroke key tables**: Emacs-style prefix keys, with a balloon showing the
  armed prefix.
- **Clipboard history**: persistent history in a popup chooser — type to filter,
  Enter pastes into the app you came from. Plus fixed snippets and scriptable
  clipboard-transform tools.
- **Window control**: move, snap/tile, minimize, activate and launch applications,
  multi-monitor aware.
- **Keyboard macros**: record and replay keys.
- **Mouse output**: send clicks, wheel scrolls and pointer moves from key bindings.
- **Console window**: live log, last-key and focus-path inspector — see exactly what to
  bind. Runs from the system tray (Windows) / menu-bar extra (macOS).

## Screenshots

| Console (macOS) | Console (Windows) |
|---|---|
| ![Keyhac console window on macOS: keyboard-hook toggle, log level selector, live key-event log, last-key and focus-path inspector](doc/images/console-mac.jpg) | ![Keyhac console window on Windows: keyboard-hook toggle, log level selector, live key-event log, last-key and focus-path inspector](doc/images/console-win.jpg) |

| Menu-bar extra (macOS) | Task tray (Windows) |
|---|---|
| ![Keyhac menu-bar extra on macOS with its menu open: Open Console, Edit Config, Reload Config, Keyboard Hook, Quit Keyhac](doc/images/menubar-extra-icon-mac.jpg) | ![Keyhac task-tray icon on Windows with its menu open: Open Console, Edit Config, Reload Config, Keyboard Hook, Quit Keyhac](doc/images/tasktray-icon-win.jpg) |

## Install

Download from [Releases](https://github.com/crftwr/keyhac2/releases):

- **macOS 15+** — `Keyhac-<version>-macos.dmg`: drag Keyhac.app into Applications and
  launch it. Grant the Accessibility permission when prompted (required for the
  keyboard hook).
- **Windows 10/11 (x64)** — `Keyhac-<version>-win64.zip`: unzip anywhere and run
  `Keyhac.exe`.

Details, data locations and privacy notes: [doc/installation.md](doc/installation.md).

## Quick start

On first run Keyhac creates `~/.keyhac/config.py` from a fully commented template.
Open it from the tray / menu-bar icon ("Edit Config"), edit, then "Reload Config".
A config defines one function:

```python
from keyhac import *

def configure(keymap):
    kt = keymap.define_keytable(focus_path_pattern="*")   # active everywhere

    kt["Fn-J"] = "Left"                        # key -> key
    kt["Fn-A"] = "Home", "Shift-End"           # key -> sequence

    def hello():                               # key -> Python function
        print("Hello from config.py")
    kt["Fn-H"] = hello

    kt["Fn-V"] = ShowClipboardHistory()        # clipboard history popup

    kt_browser = keymap.define_keytable(app="chrome|Safari")   # per-app table
    kt_browser["Fn-R"] = "Cmd-R"
```

The full reference is [doc/configuration.md](doc/configuration.md); the shipped
template ([keyhac/_config.py](keyhac/_config.py)) is a working tour of every feature.

## Documentation

- [Installation](doc/installation.md) — install, permissions, data files, privacy.
- [Configuration](doc/configuration.md) — the complete config.py reference.
- [Migrating from Keyhac for macOS](doc/migration-from-keyhac-mac.md) — mostly drop-in.
- [Migrating from Keyhac for Windows](doc/migration-from-keyhac-win.md) — API renamed;
  translation table.
- [Developer documentation](doc/dev/) — architecture, platform layer, packaging,
  testing. Project guide for coding agents: [CLAUDE.md](CLAUDE.md).

## Running from source

```sh
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest          # engine + unit tests, no permissions needed
.venv/bin/python -m keyhac          # run (macOS: needs Accessibility permission)
```

`python -m keyhac -d` enables debug logging, `--no-ui` runs headless (hook + engine
only), `--config PATH` uses an alternate config file (its data files live beside it).

## License

MIT — see [LICENSE](LICENSE).
