{"id":45271002,"url":"https://github.com/asklar/lvt","last_synced_at":"2026-03-02T21:14:18.619Z","repository":{"id":339681375,"uuid":"1162223584","full_name":"asklar/lvt","owner":"asklar","description":"A Windows CLI tool that inspects an app window's visual tree","archived":false,"fork":false,"pushed_at":"2026-02-24T00:38:14.000Z","size":399,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-24T00:49:22.223Z","etag":null,"topics":["comctl32","windows","windows-applications","winui","winui3","xaml"],"latest_commit_sha":null,"homepage":"https://asklar.dev","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asklar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-20T02:10:49.000Z","updated_at":"2026-02-24T00:38:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/asklar/lvt","commit_stats":null,"previous_names":["asklar/lvt"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/asklar/lvt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asklar%2Flvt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asklar%2Flvt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asklar%2Flvt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asklar%2Flvt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asklar","download_url":"https://codeload.github.com/asklar/lvt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asklar%2Flvt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29878459,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T23:51:21.483Z","status":"ssl_error","status_checked_at":"2026-02-26T23:50:46.793Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["comctl32","windows","windows-applications","winui","winui3","xaml"],"created_at":"2026-02-21T01:13:32.030Z","updated_at":"2026-02-27T00:17:03.540Z","avatar_url":"https://github.com/asklar.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lvt — Live Visual Tree\n\nA Windows CLI tool that inspects the visual tree of running applications. Designed for AI agents (e.g. GitHub Copilot) that need a textual representation of an app's UI content.\n\n![lvt inspecting File Explorer](docs/hero.png)\n\n![Annotated screenshot of Notepad](docs/notepad-lorem.png)\n\n## What it does\n\n- Targets any running Windows app by HWND, PID, process name, or window title\n- Detects UI frameworks in use: Win32, ComCtl, Windows XAML (UWP), WinUI 3, WPF, [Avalonia](docs/avalonia-plugin.md), [Chrome/Edge](docs/chromium-plugin.md)\n- Outputs a unified element tree as JSON or XML markup\n- Captures annotated PNG screenshots with element IDs overlaid\n- Elements get stable IDs (`e0`, `e1`, …) so AI agents can reference specific parts of the UI\n\n## Quick start\n\n### Download\n\nGrab the latest release from **[GitHub Releases](https://github.com/asklar/lvt/releases/latest)** — extract the zip and run `lvt.exe` from any terminal.\n\n### Install the Copilot skill\n\nThe easiest way to add the lvt skill to GitHub Copilot CLI is to install it as a plugin:\n\n```\n/plugin install asklar/lvt\n```\n\nThis gives Copilot the ability to inspect any running Windows app's UI when you ask it to. Verify with `/skills list`.\n\n### Build from source\n\n#### Prerequisites\n\n- Visual Studio 2022+ (C++ Desktop workload)\n- [vcpkg](https://vcpkg.io) with `VCPKG_ROOT` environment variable set\n- CMake 3.20+\n- x64 Developer Command Prompt\n\n#### Build\n\n```powershell\n# x64 build (default)\ncmake --preset default\ncmake --build build\n\n# ARM64 build\ncmake --preset arm64\ncmake --build build-arm64\n```\n\nProduces `build/lvt.exe` and `build/lvt_tap_x64.dll` (or `build-arm64/lvt.exe` and `build-arm64/lvt_tap_arm64.dll` for ARM64).\n\n\u003e **Note:** lvt.exe must match the target process's architecture. If you target an ARM64 app, use the ARM64 build. A clear error message is shown on mismatch.\n\n### Usage\n\n```bash\n# Dump Notepad's visual tree as JSON\nlvt --name notepad\n\n# XML output\nlvt --name notepad --format xml\n\n# Capture annotated screenshot\nlvt --pid 1234 --screenshot out.png\n\n# Just detect frameworks\nlvt --hwnd 0x1A0B3C --frameworks\n\n# Scope to a subtree\nlvt --name myapp --element e5 --depth 3\n\n# Screenshot + tree dump together\nlvt --name notepad --screenshot out.png --dump\n```\n\n### Options\n\n| Flag | Description |\n|------|-------------|\n| `--hwnd \u003chandle\u003e` | Target window by HWND (hex) |\n| `--pid \u003cpid\u003e` | Target process by PID |\n| `--name \u003cexe\u003e` | Target by process name (e.g. `notepad` or `notepad.exe`) |\n| `--title \u003ctext\u003e` | Target by window title substring |\n| `--output \u003cfile\u003e` | Write tree to file instead of stdout |\n| `--format \u003cfmt\u003e` | `json` (default) or `xml` |\n| `--screenshot \u003cfile\u003e` | Capture annotated screenshot to PNG |\n| `--dump` | Output the tree (default unless `--screenshot` is used) |\n| `--element \u003cid\u003e` | Scope to a specific element subtree |\n| `--frameworks` | Just list detected frameworks |\n| `--depth \u003cn\u003e` | Max tree traversal depth |\n\n## Output format\n\n### JSON\n\n```json\n{\n  \"target\": { \"hwnd\": \"0x001A0B3C\", \"pid\": 12345, \"processName\": \"Notepad.exe\" },\n  \"frameworks\": [\"win32\", \"winui3\"],\n  \"root\": {\n    \"id\": \"e0\",\n    \"type\": \"Window\",\n    \"framework\": \"win32\",\n    \"className\": \"Notepad\",\n    \"text\": \"Untitled - Notepad\",\n    \"bounds\": { \"x\": 100, \"y\": 100, \"width\": 800, \"height\": 600 },\n    \"children\": [\n      {\n        \"id\": \"e1\",\n        \"type\": \"ContentPresenter\",\n        \"framework\": \"winui3\",\n        \"bounds\": { \"x\": 108, \"y\": 140, \"width\": 784, \"height\": 552 }\n      }\n    ]\n  }\n}\n```\n\n### XML\n\n```xml\n\u003cLiveVisualTree hwnd=\"0x001A0B3C\" pid=\"12345\" process=\"Notepad.exe\" frameworks=\"win32,winui3\"\u003e\n  \u003cWindow id=\"e0\" framework=\"win32\" className=\"Notepad\" text=\"Untitled - Notepad\" bounds=\"100,100,800,600\"\u003e\n    \u003cContentPresenter id=\"e1\" framework=\"winui3\" bounds=\"108,140,784,552\" /\u003e\n  \u003c/Window\u003e\n\u003c/LiveVisualTree\u003e\n```\n\n## Architecture\n\nThe tool uses a 4-stage pipeline:\n\n1. **Target resolution** — resolve HWND/PID/name/title to a target window\n2. **Framework detection** — enumerate loaded DLLs to detect UI frameworks\n3. **Tree building** — Win32 HWND walk as base, framework providers layer on top\n4. **Serialization** — output as JSON/XML, optionally capture screenshot\n\nFramework providers:\n- **Win32Provider** — base HWND tree (always present)\n- **ComCtlProvider** — enriches ComCtl32 controls (ListView items, TreeView nodes, etc.)\n- **XamlProvider** — injects TAP DLL to walk Windows XAML visual trees\n- **WinUI3Provider** — injects TAP DLL to walk WinUI 3 visual trees\n- **WpfProvider** — walks WPF visual trees via managed DLL injection\n- **Plugins** — extensible framework support (e.g. [Avalonia](avalonia-plugin.md)) via C ABI plugin interface\n\nSee [docs/architecture.md](docs/architecture.md) for details.\n\n## Design principles\n\n- **No UI Automation** — uses framework-native APIs directly for speed and accuracy\n- **Graceful degradation** — if a framework provider fails, falls back to HWND-level info\n- **AI-first** — output formats and element IDs designed for machine consumption\n- **Minimal footprint** — single exe + one DLL, no installers, no runtime dependencies\n\n## Tests\n\n```powershell\n# Run unit tests\nbuild\\lvt_unit_tests.exe\n\n# Run integration tests (launches Notepad automatically)\nbuild\\lvt_integration_tests.exe\n\n# Via CTest\nctest --test-dir build\n```\n\n## Plugin system\n\nlvt supports a plugin architecture for adding new framework providers. Plugins are DLLs that implement a simple C interface and are loaded automatically from `%USERPROFILE%\\.lvt\\plugins\\`.\n\nSee [src/plugin.h](src/plugin.h) for the plugin interface.\n\n### Optional plugins\n\n| Plugin | Framework | Docs |\n|--------|-----------|------|\n| **Avalonia** | [Avalonia UI](https://avaloniaui.net/) desktop apps | [docs/avalonia-plugin.md](docs/avalonia-plugin.md) |\n| **Chromium** | Chrome/Edge browser DOM trees | [docs/chromium-plugin.md](docs/chromium-plugin.md) |\n\nThese plugins are built from source alongside lvt and deployed to `%USERPROFILE%\\.lvt\\plugins\\`. See each plugin's documentation for installation and usage details.\n\n## Future work\n\n- WinForms provider\n- WebView2 provider\n- MAUI provider\n- Element property querying (`--query \u003cid\u003e \u003cproperty\u003e`)\n- Accessibility tree correlation\n- Watch mode for live tree diffing\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasklar%2Flvt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasklar%2Flvt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasklar%2Flvt/lists"}