Metadata-Version: 2.4
Name: uitree
Version: 0.1.0
Summary: Desktop UI Automation trees for agents: inspect, search and diff Windows GUI element trees (pywinauto-backed, fixture-replayable offline)
Author: juzorei
License-Expression: MIT
Project-URL: Homepage, https://github.com/juzorei/uitree
Keywords: uia,ui-automation,windows,desktop-automation,agent-skills,pywinauto
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# uitree

Read desktop UI Automation trees so an agent can act on meaning, not pixels.

Windows exposes every well-behaved app as a semantic tree — controls with types, names, AutomationIds, enabled states and values. It's a DOM for the desktop. `uitree` makes that tree available to scripts and agents: dump it, search it, watch it change.

```text
$ uitree windows
      132016  (untitled)
      65908  Панель задач
      197840  ZCode

$ uitree dump "Notepad"
Window "Untitled - Notepad"  [88,232 962x468]
  MenuBar "Application"
    MenuItem "File"
    MenuItem "Edit"
  Edit "Text Editor" id=15  value=''  [96,300 946x368]
  StatusBar ...

$ uitree find "Notepad" --type Edit
  Edit         name='Text Editor' id='15'  [96,300 946x368]

$ uitree watch "Notepad" --interval 1
[2]
  + appeared: Dialog "Save As"
  + appeared: Button "Save" id=CmdSave
```

## Commands

```text
uitree windows [--json]
uitree dump <title-or-handle> [--depth N] [--json]
uitree find <window> [--name X] [--contains] [--type T] [--automation-id A] [--json]
uitree watch <window> [--interval 1] [--count 10]     # reports appeared / gone / value changes
uitree demo [dir]                                     # Notepad + Save-As fixture trees, offline
```

Read-only by contract — `uitree` never injects input, so it's safe to run against any window. Acting on an element is done through the element's AutomationId with pywinauto directly (see the skill).

Live trees are Windows-only and need [pywinauto](https://github.com/pywinauto/pywinauto) (installed automatically on Windows by pip). Everywhere else, `--fixtures <dir>` replays saved trees — which is also how the tests work and how `uitree demo` teaches the workflow without touching your screen.

Python 3.11+.

Install: `pip install uitree` — or from this repo:
`pip install "git+https://github.com/juzorei/uitree#subdirectory=tools/uitree"`

The companion agent skill lives in [skills/desktop-uia-automation](../skills/desktop-uia-automation): inspect → locate by AutomationId → act through patterns → verify by re-reading the tree. Skills: `npx skills add juzorei/uitree`.
