pctr

Element-based Windows UI Automation CLI for AI agents.

Instead of screenshotting and guessing pixel coordinates, pctr finds controls by their name / control type / automation id and acts on them. Window moves, DPI changes, and layout shifts don't break your script.

Built on pywinauto (UI Automation) with pyautogui / pydirectinput for raw mouse and keyboard input.

Install

pip install pctr

Windows only.

Commands

Command	What it does
`pctr windows [--filter RE]`	List top-level windows (`pid=… \| title`).
`pctr tree --title RE [--limit N]`	Dump the UIA control tree of a window.
`pctr find --title RE --name RE [--control-type T] [--auto-id ID]`	List matching elements.
`pctr click --title RE --name RE [--method auto\|invoke\|mouse] [--dbl]`	Click an element.
`pctr set --title RE --name RE --text S`	Set a field via the UIA ValuePattern.
`pctr type [--title RE --name RE] --text S [--delay 0.03] [--chunk 1]`	Type literal text.
`pctr keys --keys "{ENTER}"`	Send a global key combo.
`pctr hotkey --keys win+shift+s`	Send a modifier combo.
`pctr focus --title RE`	Bring a window to the foreground.
`pctr wait --title RE --name RE [--timeout S]`	Wait until an element exists.
`pctr shot [--title RE] --out PATH`	Screenshot the screen or a window.
`pctr size`	Print primary screen size as `WxH`.
`pctr move --x N --y N`	Move the cursor.
`pctr down / up [--button left]`	Press / release a mouse button.
`pctr hold --ms 1000 [--x N --y N]`	Press, hold, release.
`pctr drag --start x,y --end x,y [--duration S]`	Drag between two points.
`pctr keydown / keyup --key a`	Hold / release a keyboard key.
`pctr keyhold --key w --ms 1500`	Hold a key for a duration.

Common filters: --title (regex), --name (regex), --control-type (Button, Edit, Pane, MenuItem, …), --auto-id, --nth, --process.

The loop

pctr tree  --title "Notepad" --limit 60      # see what's clickable
pctr click --title "Notepad" --name "^File$"
pctr set   --title "Notepad" --name "Text Editor" --text "hello"

Notes

Prefer set (ValuePattern) over type for text fields - it can't drop or reorder characters.
type is sent in small chunks (--chunk 1 --delay 0.03); raise the delay for Qt/Electron apps that garble fast input.
Global type / keys go to the OS-focused window - pctr focus first.
Qt apps expose a rich tree including embedded webviews. Electron apps expose only the window frame unless accessibility is enabled (use focus + keys).

License

MIT

Metadata

Release files for pctr 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pctr 0.2.0
File	Size	Uploaded
pctr-0.2.0.tar.gz	14.0 kB	Sep 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pctr 0.2.0
File	Interpreter	ABI	Platform	Reset
pctr-0.2.0-py3-none-any.whl 13.6 kB Sep 24, 2026	Python 3	none	any	Details

Total release size: 27.6 kB

Release files / pctr-0.2.0.tar.gz

Download URL	pctr-0.2.0.tar.gz
Size	14.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`6de9a1d0feb0e5c8ba27eb42993aab42c31647ee264ec34b1cfbcfeb7d692cf1`
BLAKE2b-256 checksum How to use checksums	`ac8830349c87226e97057a309faad193bd0cb8848a07213aef9102183730fb1c`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`

Release files / pctr-0.2.0-py3-none-any.whl

Download URL	pctr-0.2.0-py3-none-any.whl
Size	13.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`23ceb659d992f73b2068b2905e0d9730e1ed6a08b14747434c475882463b9da5`
BLAKE2b-256 checksum How to use checksums	`af2c2a0861c6c9f992f6de863cdf4da061a1866fd08a46bd4bfe9bfd773e8335`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`