Skip to content

autoShell

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

autoShell

README.md

AutoShell

A Windows shell automation console application that provides a JSON-based command interface for controlling Windows applications, audio settings, themes, and window management.

Overview

AutoShell is part of the TypeAgent project. It runs as a console application that reads JSON commands from stdin and executes Windows shell operations. This enables programmatic control of the Windows desktop environment.

Features

  • Application Management: Launch, close, and switch between applications using friendly names
  • Window Management: Maximize, minimize, and tile windows side-by-side
  • Audio Control: Set volume levels, mute/unmute, and restore previous volume
  • Theme & Personalization: Apply themes, set wallpaper, toggle transparency, and configure title bar colors
  • Virtual Desktop Management: Create, switch, pin, and move windows across virtual desktops
  • Display Settings: Set resolution, brightness, scaling, orientation, color temperature, and blue light filter
  • Network & Connectivity: Wi-Fi, Bluetooth, airplane mode, and metered connection controls
  • Mouse & Touchpad: Cursor speed, pointer size, scroll lines, touchpad settings, and cursor trail
  • Taskbar Customization: Alignment, auto-hide, badges, Task View, Widgets, and multi-monitor display
  • Accessibility: Narrator, Magnifier, Sticky Keys, Filter Keys, and mono audio
  • Privacy Controls: Manage camera, microphone, and location access
  • Power Management: Battery saver levels and power mode configuration
  • System Settings: Notifications, game mode, focus assist, time settings, and multi-monitor behavior
  • File Explorer: Toggle file extensions and hidden/system file visibility

Requirements

Building

dotnet build AutoShell.csproj

Usage

AutoShell runs in two modes:

Interactive mode (default): Run the application and send JSON commands via stdin, one per line:

dotnet run --project autoShell.csproj
{"Volume":50}
{"Mute":true}
{"quit":null}

Command-line mode: Pass a JSON command (or array) as an argument for one-shot execution:

autoShell.exe {"Volume":50}
autoShell.exe [{"Volume":50},{"Mute":true}]

Command Reference

Core Commands

Command Parameter Description
ApplyTheme Theme name Applies a Windows theme
CloseProgram Application name Closes an application
ConnectWifi {"ssid": "name", "password": "pass"} Connects to a Wi-Fi network
CreateDesktop JSON array of names Creates one or more virtual desktops
Debug (none) Launches the debugger
DisconnectWifi (none) Disconnects from the current Wi-Fi network
LaunchProgram Application name Opens an application (or raises if already running)
ListAppNames (none) Outputs installed applications as JSON
ListResolutions (none) Outputs available display resolutions as JSON
ListThemes (none) Outputs installed themes as JSON
ListWifiNetworks (none) Lists available Wi-Fi networks as JSON
Maximize Application name Maximizes the application window
Minimize Application name Minimizes the application window
MoveWindowToDesktop {"process": "app", "desktop": "name"} Moves a window to a specific virtual desktop
Mute true/false Mutes or unmutes system audio
NextDesktop (none) Switches to the next virtual desktop
PinWindow Application name Pins a window to appear on all virtual desktops
PreviousDesktop (none) Switches to the previous virtual desktop
quit (none) Exits the application
RestoreVolume (none) Restores previously saved volume level
SetScreenResolution "WIDTHxHEIGHT" or {"width": W, "height": H} Sets the display resolution
SetTextSize 100-225 Sets system text scaling percentage
SetThemeMode "light", "dark", "toggle", or boolean Sets light/dark mode
SetWallpaper File path Sets the desktop wallpaper
SwitchDesktop Index or name Switches to a virtual desktop by index or name
SwitchTo Application name Brings application window to foreground
Tile "app1,app2" Tiles two applications side-by-side
ToggleAirplaneMode true/false Enables or disables Windows airplane mode
ToggleNotifications (none) Toggles the Windows notification center
Volume 0-100 Sets system volume percentage

Settings Commands

Network Settings
Command Parameter Description
BluetoothToggle {"enableBluetooth": true/false} Toggles Bluetooth on/off
EnableMeteredConnections (none) Opens network status settings
EnableWifi {"enable": true/false} Enables or disables Wi-Fi
Display Settings
Command Parameter Description
AdjustColorTemperature (none) Opens Night light settings
AdjustScreenBrightness {"brightnessLevel": "increase"/"decrease"} Adjusts screen brightness ±10%
AdjustScreenOrientation (none) Opens display settings
DisplayResolutionAndAspectRatio (none) Opens display settings
DisplayScaling {"sizeOverride": "150"} Opens display settings; targets a DPI percentage
EnableBlueLightFilterSchedule {"nightLightScheduleDisabled": true/false} Enables or disables blue light filter schedule
RotationLock {"enable": true/false} Enables or disables rotation lock
Personalization Settings
Command Parameter Description
ApplyColorToTitleBar {"enableColor": true/false} Applies accent color to title bars
EnableTransparency {"enable": true/false} Enables or disables transparency effects
HighContrastTheme (none) Opens high contrast settings
SystemThemeMode {"mode": "light"/"dark"} Sets the system theme mode
Taskbar Settings
Command Parameter Description
AutoHideTaskbar {"hideWhenNotUsing": true/false} Auto-hides the taskbar
DisplaySecondsInSystrayClock {"enable": true/false} Shows seconds in system tray clock
DisplayTaskbarOnAllMonitors {"enable": true/false} Displays taskbar on all monitors
ShowBadgesOnTaskbar {"enableBadging": true/false} Shows or hides badges on taskbar
TaskbarAlignment {"alignment": "left"/"center"} Sets taskbar alignment
TaskViewVisibility {"visibility": true/false} Shows or hides Task View button
ToggleWidgetsButtonVisibility {"visibility": "show"/"hide"} Shows or hides Widgets button
Mouse & Touchpad Settings
Command Parameter Description
AdjustMousePointerSize (none) Opens mouse pointer settings
CursorTrail {"enable": true/false, "length": 2-12} Enables/disables cursor trail (length: 2–12)
EnableTouchPad (none) Opens touchpad settings
EnhancePointerPrecision {"enable": true/false} Enables or disables pointer precision
MouseCursorSpeed {"speedLevel": 1-20} Sets mouse cursor speed (default 10)
MousePointerCustomization (none) Opens mouse pointer settings
MouseWheelScrollLines {"scrollLines": 1-100} Sets mouse wheel scroll lines (default 3)
SetPrimaryMouseButton {"primaryButton": "left"/"right"} Sets primary mouse button
TouchpadCursorSpeed (none) Opens touchpad settings
Privacy Settings
Command Parameter Description
ManageCameraAccess {"accessSetting": "allow"/"deny"} Manages camera access
ManageLocationAccess {"accessSetting": "allow"/"deny"} Manages location access
ManageMicrophoneAccess {"accessSetting": "allow"/"deny"} Manages microphone access
Power Settings
Command Parameter Description
BatterySaverActivationLevel {"thresholdValue": 0-100} Sets battery saver activation level
SetPowerModeOnBattery (none) Opens power settings
SetPowerModePluggedIn (none) Opens power settings
Accessibility Settings
Command Parameter Description
EnableFilterKeysAction (none) Toggles Filter Keys
EnableMagnifier (none) Toggles Magnifier
EnableNarratorAction (none) Toggles Narrator
EnableStickyKeys (none) Toggles Sticky Keys
MonoAudioToggle (none) Toggles mono audio
File Explorer Settings
Command Parameter Description
ShowFileExtensions {"enable": true/false} Shows or hides file extensions
ShowHiddenAndSystemFiles {"enable": true/false} Shows or hides hidden and system files
System Settings
Command Parameter Description
AutomaticDSTAdjustment {"enable": true/false} Enables or disables automatic DST adjustment
AutomaticTimeSettingAction (none) Opens date/time settings
EnableGameMode (none) Opens Game Mode settings
EnableQuietHours (none) Opens quiet hours / focus assist settings
MinimizeWindowsOnMonitorDisconnectAction (none) Opens display settings
RememberWindowLocations (none) Opens display settings

Examples

Launch a program:

{"LaunchProgram": "notepad"}

Set the system volume at 50%:

{"Volume": 50}

Tile notepad on the left and calculator on the right of the screen:

{"Tile": "notepad,calculator"}

Apply the 'dark' Windows theme:

{"ApplyTheme": "dark"}

Set dark mode:

{"SetThemeMode": "dark"}

Toggle between light and dark mode:

{"SetThemeMode": "toggle"}

Mute the system audio:

{"Mute": true}

Set the desktop wallpaper:

{"SetWallpaper": "C:\\Users\\Public\\Pictures\\wallpaper.jpg"}

Quit AutoShell:

{"quit": null}

Create a new virtual desktop named "Design Work":

{"CreateDesktop": "Design Work"}

Toggle the Windows notification center:

{"ToggleNotifications": true}

Enable airplane mode:

{"ToggleAirplaneMode": true}

Disable airplane mode:

{"ToggleAirplaneMode": false}

List available Wi-Fi networks:

{"ListWifiNetworks": true}

Connect to a Wi-Fi network:

{"ConnectWifi": {"ssid": "MyNetwork", "password": "MyPassword123"}}

Set system text size to 125%:

{"SetTextSize": 125}

List available display resolutions:

{"ListResolutions": true}

Set display resolution to 1920x1080:

{"SetScreenResolution": "1920x1080"}

Set display resolution with specific refresh rate:

{"SetScreenResolution": "1920x1080@144"}

Set display resolution using JSON object:

{"SetScreenResolution": {"width": 2560, "height": 1440, "refreshRate": 60}}

Enable cursor trail with length 7:

{"CursorTrail": "{\"enable\":true,\"length\":7}"}

Disable cursor trail:

{"CursorTrail": "{\"enable\":false}"}

Supported Application Friendly Names

AutoShell recognizes these friendly names (case-insensitive):

  • chrome, edge, microsoft edge
  • word, winword, excel, powerpoint, power point, outlook
  • visual studio, visual studio code
  • notepad, paint, paint 3d, calculator
  • file explorer, control panel, task manager
  • cmd, powershell
  • snipping tool, magnifier
  • spotify, copilot, m365 copilot

Additionally, AutoShell automatically discovers all installed Windows Store applications by their display names.

Architecture

AutoShell uses a handler-based architecture with dependency injection. All platform-specific (P/Invoke, COM, WMI) code is isolated behind service interfaces, keeping handlers thin and fully unit-testable.

autoShell/
├── AutoShell.cs              # Entry point — stdin/stdout command loop
├── CommandDispatcher.cs      # Routes JSON keys to handlers; Create() wires all dependencies
├── IAppRegistry.cs           # App registry interface (shared across handlers)
├── WindowsAppRegistry.cs     # Maps friendly app names to paths and AppUserModelIDs
├── Handlers/
│   ├── ICommandHandler.cs    # Handler interface (SupportedCommands + Handle)
│   ├── AppCommandHandler.cs          # LaunchProgram, CloseProgram, ListAppNames
│   ├── AudioCommandHandler.cs        # Volume, Mute, RestoreVolume
│   ├── DisplayCommandHandler.cs      # SetScreenResolution, ListResolutions, SetTextSize
│   ├── NetworkCommandHandler.cs      # ConnectWifi, ToggleAirplaneMode, etc.
│   ├── SystemCommandHandler.cs       # Debug, ToggleNotifications
│   ├── ThemeCommandHandler.cs        # ApplyTheme, ListThemes, SetThemeMode, SetWallpaper
│   ├── VirtualDesktopCommandHandler.cs  # CreateDesktop, SwitchDesktop, PinWindow, etc.
│   ├── WindowCommandHandler.cs       # Maximize, Minimize, SwitchTo, Tile
│   └── Settings/
│       ├── AccessibilitySettingsHandler.cs
│       ├── DisplaySettingsHandler.cs
│       ├── FileExplorerSettingsHandler.cs
│       ├── MouseSettingsHandler.cs
│       ├── PersonalizationSettingsHandler.cs
│       ├── PowerSettingsHandler.cs
│       ├── PrivacySettingsHandler.cs
│       ├── SystemSettingsHandler.cs
│       └── TaskbarSettingsHandler.cs
├── Services/                 # Interfaces + Windows implementations
│   ├── IAudioService.cs / WindowsAudioService.cs
│   ├── IBrightnessService.cs / WindowsBrightnessService.cs
│   ├── IDebuggerService.cs / WindowsDebuggerService.cs
│   ├── IDisplayService.cs / WindowsDisplayService.cs
│   ├── INetworkService.cs / WindowsNetworkService.cs
│   ├── IProcessService.cs / WindowsProcessService.cs
│   ├── IRegistryService.cs / WindowsRegistryService.cs
│   ├── ISystemParametersService.cs / WindowsSystemParametersService.cs
│   ├── IVirtualDesktopService.cs / WindowsVirtualDesktopService.cs
│   ├── IWindowService.cs / WindowsWindowService.cs
│   └── Interop/
│       ├── CoreAudioInterop.cs   # COM interop definitions for Windows audio
│       └── UIAutomation.cs       # UI Automation helpers (last-resort)
├── Logging/
│   ├── ILogger.cs            # Logging interface (Error, Warning, Info, Debug)
│   └── ConsoleLogger.cs      # Colored console + diagnostics output
└── autoShell.Tests/          # unit, integration, and E2E tests

Key design decisions

  • CommandDispatcher.Create() is the composition root — it creates all concrete services and wires them into handlers. Tests bypass this and inject mocks directly.
  • Handlers are thin — they parse JSON parameters and delegate to services. No P/Invoke or COM code lives in handlers.
  • Services own all platform calls — P/Invoke, COM, WMI, and registry access are encapsulated behind interfaces (I*Service / Windows*Service).
  • ILogger abstracts all diagnostic output with four levels: Error (red), Warning (yellow), Info (cyan), and Debug (diagnostics only). ConsoleLogger preserves the original colored formatting.

License

Copyright (c) Microsoft Corporation. Licensed under the MIT License.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines.