Skip to main content
Glama
README.md
# 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.

```console
$ 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.

## Install

```bash
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)

```json
{ "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](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.