DesktopManager: Skill for Codex

DesktopManager Operator

Use this skill to operate the Windows desktop through DesktopManager.

Golden Path

1. Prefer MCP first: desktopmanager mcp serve
   • Add --allow-mutations only when the session really needs desktop or saved-state changes.
   • Add --allow-process <pattern> or --deny-process <pattern> when the session should stay scoped to specific desktop apps.
   • Add --allow-foreground-input only for sacrificial or tightly controlled sessions that may need focused fallback on zero-handle UIA text or key actions.
   • Add --dry-run when you want to preview mutating MCP calls without changing the desktop.
2. Start with inspection, not mutation.
   • Read resources first: desktop://windows/active desktop://windows/visible desktop://monitors
   • Use get_active_window when focus matters.
   • Use window_exists or active_window_matches when you need an explicit assertion first.
   • Use screenshot_desktop or screenshot_window when visual confirmation is needed.
   • Use get_window_geometry when you need exact outer-window and client-area bounds before a coordinate-based action.
   • When more than one window matches, switch to an exact handle before mutating anything.
3. Launch and wait when the target app is not ready yet.
   • Use launch_process to start the app.
   • Prefer launch_and_wait_for_window when the next step depends on a real launched window instead of a best-effort process start.
   • If launch correlation matters, set a short launch-time window wait instead of assuming the first matching app window is the new one.
   • If you know the expected launched window, pass a title or class filter and require a real match.
   • Use wait_for_window before moving, focusing, or capturing it.
4. Inspect controls before interacting.
   • Use list_window_controls to discover control handles, classes, text, automation ids, control types, and control bounds.
   • Use diagnose_window_controls when a modern app is not exposing the controls you expected. It will show whether Win32 or UIA discovery produced anything, whether foreground preparation helped, and what each probed UIA root returned.

• diagnose_window_controls can also take a saved control target name, so reusable target profiles and ad-hoc selectors share the same diagnostic path.
• diagnose_window_controls can also include a read-only action probe, which is the safest way to verify repeated UIA action caching without mutating the app.
• The control diagnostics payload now includes elapsed times, so you can compare cold versus warm-cache behavior directly instead of inferring it only from cache flags.
  • Use UIA-oriented selectors when modern apps do not expose useful child-window controls.
  • Use control_exists or wait_for_control when the control can appear asynchronously or when you want an explicit precondition before clicking.
  • Use assert_control_value when the workflow depends on the field content itself, not merely the presence of a matching control.
  • When available, prefer value, enabled, or focusable checks over brittle text-only guesses.
  • If UIA discovery is flaky on a background window, retry with the shared foreground hint before inventing wrapper-specific workarounds.
  • If the app still stays structurally opaque, switch to the shared coordinate-based fallback: capture the window, inspect its geometry, then use click_window_point, drag_window_points, or scroll_window_point.
  • When the same visual region matters across runs, save it as a named target area and reuse it from screenshot_window with targetName or screenshot target.
  • Prefer ratio-based client-area targeting when the same workflow must survive different window sizes.
  • If you will reuse the same fallback point more than once, save it as a named target instead of repeating raw ratios or pixels.
  • Use type_window_text for whole-window entry.
  • Use send_window_keys for whole-window Enter, Escape, or accelerator follow-up actions when the window is reliable but a modern control is not.
  • Use click_control, set_control_text, or send_control_keys for control-level work.
  • For classic handle-backed controls, prefer set_control_text or send_control_keys over foreground-dependent hacks because they now route directly to the control.
  • For zero-handle UIA controls in modern apps, foreground-based text or key fallback exists in the shared library too, but treat it as an explicit opt-in for sacrificial or tightly controlled windows.
  • When you do opt into foreground text fallback, the shared library revalidates the exact focused target and emits Unicode input directly without changing the clipboard.

1. Prefer named state over one-off moves.
   • Use list_named_layouts before manually moving windows.
   • Use apply_named_layout or restore_saved_snapshot when the desired setup already exists.
   • Use assert_window_layout when the next step depends on the saved layout actually being satisfied, not just available.
2. Make the smallest safe change.
   • Prefer focus_window, snap_window, or minimize_windows.
   • Save the current state before larger changes: save_current_layout save_current_snapshot
3. Explain what changed after mutating actions.
4. Use CLI only as fallback or verification.
5. When a mutation matters, ask for evidence.
   • Mutating MCP tools now accept captureBefore, captureAfter, and artifactDirectory.
   • Their structured results include success, elapsedMilliseconds, safetyMode, optional target name/kind, best-effort before/after screenshots, and artifact warnings.
   • Prefer captureAfter by default and add captureBefore when you need a stronger audit trail.
   • Remember that the MCP server is now read-only by default, so a failed mutating tool call may be a policy block rather than a selector failure.