DesktopManager

# DesktopManager - C# Library and PowerShell Module

DesktopManager is a Windows desktop automation toolkit available as a .NET library, PowerShell module, CLI, MCP server, and tray app.

[![nuget downloads](https://img.shields.io/nuget/dt/DesktopManager?label=nuget%20downloads)](https://www.nuget.org/packages/DesktopManager)
[![nuget version](https://img.shields.io/nuget/v/DesktopManager)](https://www.nuget.org/packages/DesktopManager)

You can also download it from PowerShell Gallery

[![PowerShell Gallery Version](https://img.shields.io/powershellgallery/v/DesktopManager.svg?style=flat-square)](https://www.powershellgallery.com/packages/DesktopManager)
[![PowerShell Gallery Preview Version](https://img.shields.io/powershellgallery/v/DesktopManager.svg?label=powershell%20gallery%20preview&colorB=yellow&style=flat-square&include_prereleases)](https://www.powershellgallery.com/packages/DesktopManager)
[![PowerShell Gallery Downloads](https://img.shields.io/powershellgallery/dt/DesktopManager.svg?style=flat-square)](https://www.powershellgallery.com/packages/DesktopManager)

[![PowerShell Gallery Platform](https://img.shields.io/powershellgallery/p/DesktopManager.svg?style=flat-square)](https://www.powershellgallery.com/packages/DesktopManager)
[![GitHub top language](https://img.shields.io/github/languages/top/evotecit/DesktopManager.svg?style=flat-square)](https://github.com/EvotecIT/DesktopManager)
[![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/evotecit/DesktopManager.svg?style=flat-square)](https://github.com/EvotecIT/DesktopManager)
[![GitHub license](https://img.shields.io/github/license/EvotecIT/DesktopManager.svg?style=flat-square)](https://github.com/EvotecIT/DesktopManager)

If you would like to contact me you can do so via Twitter or LinkedIn.

[![Twitter Follow](https://img.shields.io/twitter/follow/PrzemyslawKlys.svg?label=Twitter%20%40PrzemyslawKlys&style=social)](https://twitter.com/PrzemyslawKlys)
[![Blog evotec.xyz](https://img.shields.io/badge/Blog-evotec.xyz-2A6496.svg)](https://evotec.xyz/hub)
[![LinkedIn pklys](https://img.shields.io/badge/LinkedIn-pklys-0077B5.svg?logo=LinkedIn)](https://www.linkedin.com/in/pklys)
[![Discord](https://img.shields.io/discord/508328927853281280?style=flat-square&label=discord%20chat)](https://evo.yt/discord)
[![Threads @PrzemyslawKlys](https://img.shields.io/badge/Threads-@PrzemyslawKlys-000000.svg?logo=Threads&logoColor=White)](https://www.threads.net/@przemyslaw.klys)


## What it's all about

<img height="256" align="right" src="Assets/Images/DesktopManager.jpg">

DesktopManager provides one shared Windows automation core through five surfaces:

- **C# library** for .NET applications and services
- **PowerShell module** for scripts and operator workflows
- **CLI executable** for terminal and JSON automation
- **MCP server** for inspect-first agent automation
- **Windows tray app** for daily hotkeys and monitor actions

It has following features:
- Get information about monitors
- Get information about display devices
- Get information about wallpapers
- Set wallpapers
- Get/Set desktop background color
- Get/Set monitor position
- Get/Set window position
- Get/Set window state (minimize, maximize, restore)
 - Capture desktop screenshots from all monitors, a single monitor or a custom region
- Manage monitor brightness
- Start/Stop/Advance wallpaper slideshows
- Track wallpaper history
- Adjust monitor resolution and orientation
- Move monitors around the virtual desktop
- Save and restore window layouts
- Snap or move windows between monitors
- Subscribe to resolution, orientation or display changes
- Keep inactive windows awake using periodic input
- Manage keep-alive sessions for windows
- Save and restore cohesive workstation profiles across displays, audio, personalization, and taskbars
- Enumerate Core Audio render/capture endpoints, change volume and mute, set default roles, and observe endpoint changes
- Inspect power and interactive-session state; lock, sign out, sleep, hibernate, or hold a bounded keep-awake lease
- Capture and restore personalization snapshots and configure taskbar visibility, position, and auto-hide
- Enumerate, observe, and explicitly enable or disable Wi-Fi, Bluetooth, mobile broadband, and FM radios through the supported Windows radio API
- List saved Windows Wi-Fi profiles and connect an exact saved profile without scanning nearby networks or exposing credentials
- Inspect a window's virtual desktop and move it to a known desktop through the public Windows virtual-desktop API
- Inspect and manage Plug and Play devices and Driver Store packages through documented native Windows APIs

### Desktop state and controls

The workstation profile is the high-level entrypoint when you want to move between repeatable setups. It captures connected monitor modes and placement, monitor wallpaper and supported brightness/HDR state, active audio endpoint state and default roles, personalization, and taskbars. Applying a profile matches monitors by stable identity, stages display changes together, and rolls back the selected sections when a required step fails. Machine-wide personalization policies are captured but only restored when explicitly requested.

```powershell
Save-DesktopWorkstationProfile -Name 'office'
Get-DesktopAudioEndpoint -DataFlow Render -State Active
Get-DesktopPowerStatus
Get-DesktopSession
Get-DesktopRadio
Get-DesktopWifiProfile
Connect-DesktopWifiProfile -Name 'Corporate WiFi'
Get-DesktopDevice -Present -Problem
Get-DesktopDriverPackage
Restore-DesktopWorkstationProfile -Name 'office' -Confirm
```

The same capabilities are available from the CLI:

```text
desktopmanager workstation save --name office
desktopmanager audio list --flow render --active
desktopmanager system power
desktopmanager system session
desktopmanager radio list
desktopmanager wifi profiles
desktopmanager wifi connect --profile "Corporate WiFi"
desktopmanager device list --present --problem
desktopmanager driver list
desktopmanager workstation apply --name office
```

Radio control has two deliberately separate APIs. `RadioService` and the normal `radio list` / `radio set` commands use the supported `Windows.Devices.Radios` contract for individual radios. Global airplane mode uses an undocumented Windows shell COM contract, so it lives under `ExperimentalAirplaneModeService` and requires `--experimental` in the CLI, `-Experimental` in PowerShell, or `--allow-experimental` in MCP.

Wi-Fi profile connection is separate from radio control. `WifiProfileService`, `Get-DesktopWifiProfile`, and `desktopmanager wifi profiles` enumerate only profiles already stored by Windows. Connecting an exact profile uses the Native Wi-Fi profile API and ACM completion notifications; it does not scan nearby networks, return BSSIDs, expose profile XML or credentials, or query location-sensitive current-connection details. Windows still requires location consent for nearby-network scanning and related Wi-Fi information APIs. See [Changes to API behavior for Wi-Fi access and location](https://learn.microsoft.com/windows/win32/nativewifi/wi-fi-access-location-changes).

`VirtualDesktopService` exposes only the public Windows operations: check whether a top-level window is on the current desktop, get its desktop ID, and move it to a known desktop ID. Desktop enumeration, creation, renaming, switching, and removal are intentionally not presented as supported APIs.

Additional operator-focused docs for the newer CLI and MCP surfaces:

- [Docs/DesktopManager.Cli.md](Docs/DesktopManager.Cli.md)
- [Docs/DesktopManager.Mcp.md](Docs/DesktopManager.Mcp.md)
- [Docs/DesktopManager.Architecture.md](Docs/DesktopManager.Architecture.md)
- [Docs/DesktopManager.DesktopState.md](Docs/DesktopManager.DesktopState.md)
- [Docs/DesktopManager.DeviceManagement.md](Docs/DesktopManager.DeviceManagement.md)
- [Docs/DesktopManager.AutomationBasics.md](Docs/DesktopManager.AutomationBasics.md)
- [Docs/DesktopManager.Plugin.md](Docs/DesktopManager.Plugin.md)
- [.agents/skills/desktopmanager-operator/SKILL.md](.agents/skills/desktopmanager-operator/SKILL.md)
- [.agents/skills/desktopmanager-build/SKILL.md](.agents/skills/desktopmanager-build/SKILL.md)

## Which Surface Should You Use?

| Surface | Best for | Typical entrypoint |
| ------- | -------- | ------------------ |
| C# library | Embedding DesktopManager into your own .NET app or service | `DesktopManager.dll` |
| PowerShell module | Scripts, operators, admin workflows, repeatable task automation | `Install-Module DesktopManager` |
| CLI executable | Manual use, shell automation, JSON output, and MCP hosting | `desktopmanager.exe` |
| MCP server | Agent-driven automation over stdio with an inspect-first safety model | `desktopmanager mcp serve` |
| Windows tray app | Daily hotkeys, monitor bindings, HDR controls, tray runtime, and per-user startup | `DesktopManager.App.exe` |

## How It Fits Together

DesktopManager now has one shared core and several operator-facing surfaces on top of it.

```mermaid
flowchart LR
    A["Your .NET app"] --> B["DesktopManager library"]
    C["PowerShell module"] --> B
    D["desktopmanager.exe CLI"] --> B
    E["MCP server"] --> D
    J["DesktopManager.App tray app"] --> B
    B --> F["Windows desktop APIs"]
    F --> G["Monitors / wallpapers / brightness"]
    F --> H["Windows / controls / input"]
    F --> I["Layouts / snapshots / targets"]
```

If you want the fuller component and request-flow diagrams, see [Docs/DesktopManager.Architecture.md](Docs/DesktopManager.Architecture.md).

The practical way to think about this:

- use the library when DesktopManager is part of your own application
- use PowerShell when you want scriptable admin/operator automation
- use the CLI when you want a human-friendly or JSON-friendly command surface
- use MCP when an agent should inspect first and mutate only through an explicit server session

## Common Entry Points

| Goal | Recommended entryp