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.1.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.1.0
File	Size	Uploaded
pctr-0.1.0.tar.gz	9.1 kB	Sep 24, 2026	Details

Built distribution (wheel)

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

Total release size: 17.0 kB

Release files / pctr-0.1.0.tar.gz

Download URL	pctr-0.1.0.tar.gz
Size	9.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`1c5b0ebc39c16bbe80535331fc693943f8a2fdebb5671e8c6242e4a6ab66a345`
BLAKE2b-256 checksum How to use checksums	`e33594d434382d56d5d51f9efe27ae49d2101b8f6fbcb36d6a7b81ed12a270f6`
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.1.0-py3-none-any.whl

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