🌳 vdtree

A lightweight, standalone CLI utility to map Windows Virtual Desktops and open windows.

Ever lost a window off-screen after unplugging a monitor? Or wanted a quick, readable map of exactly what applications are scattered across your Windows Workspaces?

vdtree embraces the Unix Philosophy ("Do one thing, and do it well") but applies it to the Windows Desktop UI layer. It acts as a highly detailed ls or tree command specifically for your graphical environment.

✨ Features

• Standalone Executable: Download the single .exe and run it. All Python libraries and Win32 bindings are bundled inside. No runtime installation or setup required.
• Workspace Mapping: Translates undocumented Windows COM internal IDs into human-readable Desktop Numbers (e.g., Desktop 1, Desktop 2).
• Pinned Window Detection: Correctly identifies apps mirrored to "Show on all desktops".
• Geometry Tracking: Reports exact X/Y coordinates and dimensions (useful for finding off-screen windows).
• Scriptable: Includes a --json flag to dump the topology for consumption by other scripts.

🚀 Installation & Usage

For Standard Users:

1. Go to the Releases page and download vdtree.exe.
2. Open Windows Terminal, PowerShell, or Command Prompt.
3. Run the tool:

   .\vdtree.exe

Available Commands:

# Print the standard human-readable table
.\vdtree.exe

# Output the raw data in JSON format
.\vdtree.exe --json

# Show the help menu
.\vdtree.exe -h

🛠️ Building from Source (For Developers)

If you prefer to run the raw Python script or compile it yourself:

1. Ensure you have Python 3.10+ installed.
2. Clone the repository and install the requirements:

   git clone https://github.com/yourusername/vdtree.git
   cd vdtree
   pip install -r requirements.txt

3. Run the script directly:

   python vdtree.py

4. Compile to .exe:

   python -m PyInstaller --onefile vdtree.py

   The compiled executable will be located in the dist/ folder.

⚙️ Compatibility

• OS: Windows 10 and Windows 11 (Requires OS-level Virtual Desktop support).
• Architecture: 64-bit (x64) Windows.

📝 Background

This project is an offshoot of a larger session management tool. It was spun out to provide a highly reliable, read-only inspection tool that doesn't break during Windows OS updates.