Skip to main content
Glama

winepilot

Will this Windows app run on Linux, and what do I do about it? One command, an answer with evidence.

winepilot is an open-source CLI, MCP server and agent skill that sits on top of Wine/Proton. You (or your AI agent) get a verdict and exact next steps instead of a maze of prefixes, winetricks verbs and forum threads.

$ winepilot check setup.exe
setup.exe
  verdict : MAYBE  (DirectX 12 title: works with VKD3D-Proton on a modern Vulkan GPU, results vary.)
  type    : x64 gui
  needs   : vkd3d-proton - Direct3D 12 -> VKD3D-Proton (needs Vulkan 1.3 GPU)  [d3d12.dll]
  try     : winetricks -q vcrun2022

Status (honest)

Feature

State

check: static PE analysis (arch, DirectX, VC++/.NET runtimes, anti-cheat detection)

working, tested

doctor: probes Wine, winetricks, Vulkan, Xvfb, GPU, prints fix commands

working, tested

MCP server (check_windows_app, doctor_machine, run_windows_app)

working, stdio handshake tested

run: isolated prefix, observation window, log hints

implemented; not yet validated against a real Wine install (needs contributors with Wine)

Screenshot capture, retry loop, recipe export/import

planned

Community recipe repo, ProtonDB/Lutris/Bottles importers

planned

Android apps via Waydroid

planned

Static analysis gives a prediction, not a guarantee. Only run produces runtime evidence, and winepilot says "ran" only if the program exited cleanly or stayed alive for the observation window.

Related MCP server: Windows-MCP

Install

pip install "winepilot[mcp]"      # or: uv tool install "winepilot[mcp]"
winepilot doctor                    # what's missing on this machine
winepilot check game.exe --json
winepilot run game.exe --observe 20

Use from an AI agent (MCP)

{ "mcpServers": { "winepilot": { "command": "winepilot", "args": ["mcp"] } } }

Or copy skill/SKILL.md into your agent's skills folder.

Anti-cheat

winepilot detects kernel-level anti-cheat (Vanguard, FACEIT, XIGNCODE3, GameGuard) and conditional ones (EAC, BattlEye, Denuvo) and tells you the truth. It will never help evade or bypass them.

Design

  • Zero runtime dependencies for the core (own PE reader); mcp is optional.

  • Evidence-first: every finding lists the DLL or string that caused it.

  • --json everywhere so agents can parse it.

Contributing

See CONTRIBUTING.md. The most valuable help: run winepilot run on a real Wine setup and report what is wrong, or add rules in rules.py with a test.

Licensed under Apache-2.0. Not affiliated with WineHQ, Valve, or CodeWeavers.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to automate Linux desktop GUI by launching and interacting with Wayland applications in isolated virtual KWin sessions, or connecting to live desktops for collaborative automation.
      162 PyPI
      81
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI coding agents to reverse engineer an operating system from its ISO and rebuild it component by component, exposing 39 tools over stdio for ISO fingerprinting, sandboxed QEMU VM lifecycle, PE analysis, API-surface dumps, syscall tracing, behavior diffs, component scaffolding, compat shims, app-compat testing, and knowledge-base search. It lets an agent survey a reference OS, generate clean-room specs and code, boot the rebuild, and test real applications against it.
      39
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI coding agents to work inside a disposable Windows guest desktop, where they can run shell commands, launch applications, inspect and operate native GUI controls, perform browser DOM actions, and transfer files. Fresh observations, PNG screenshots, and hashed artifacts let agents verify results without touching the host desktop.
      18
      MIT