Wine on macOS with an AI agent: a diagnosis skill for Windows apps

TL;DR

• The repository is a knowledge base and skill for AI agents to diagnose and solve problems running Windows games, applications and software on macOS — through any Wine-based compatibility layer.
• It covers CrossOver, vanilla Wine, Whisky, Kegworks and Wineskin, Bottles and Apple's Game Porting Toolkit, with what each one is best at and how an agent can reach it.
• Almost all troubleshooting reduces to four questions: which prefix the app lives in, which Windows version it emulates, which DLLs and runtimes are installed, and whether the failure is at install, launch or runtime.
• It ships a workflow, a tool comparison, prefix locations per tool, debugging with WINEDEBUG, the winetricks fixes and a database of common issues.

What it is and who it is for

Wine macOS AI Runner is a skill and reference set for AI agents — Cursor, Claude Code, Codex, GitHub Copilot, Windsurf and the rest — plus a human-facing documentation set.

It is for the person who has a Windows program that "should work" on a Mac and does not, and for the agent that has to help them. The README's framing is the useful part: this is not only Wine. The compatibility landscape on macOS is six overlapping tools, and the skill's job is to identify which one the person has before diagnosing anything.

The tools it covers

The four questions

The README reduces almost all troubleshooting to four:

1. Which prefix or bottle is the app installed in?
2. Which Windows version is that prefix emulating — Windows 7, 10 or 11?
3. Which DLLs and runtimes are installed — DirectX, .NET, VCRedist, DXVK?
4. Is the failure at install, launch or runtime?

That reduction is the reason the skill is useful to an agent: the first question is not "which flag do I pass to Wine", it is "where is the prefix", and an agent that guesses without locating the prefix changes settings in the wrong bottle.

The README also lists the common prefix locations per tool — CrossOver bottles under ~/Library/Application Support/CrossOver/Bottles/<BottleName>/, vanilla Wine under ~/.wine/ or the newer Homebrew default, Whisky under its Bottles/<uuid>/ folder, and a Kegworks or Wineskin wrapper inside /Applications/YourApp.app/Contents/Resources/.

Apple Silicon and Intel

The overhead figure is a performance note, not a measurement you get to assume for a specific game.

What the agent can do with it

The README lists the agent-facing capabilities: identify which tool the person has, locate the correct bottle or prefix automatically, check WineHQ AppDB or CrossOver compatibility for known recipes, apply the correct Windows version with DLL overrides and DXVK or vkd3d settings, read and interpret WINEDEBUG logs with +loaddll,+seh,+module, fix missing DLLs through winetricks with d3dx9, vcrun2019, dotnet48 and dxvk, diagnose black screens, crashes, audio and controller problems, and identify hard blockers such as kernel anti-cheat, unsupported DRM and DirectX 12 gaps.

That last category is the honest one. A kernel anti-cheat that refuses to run is not a DLL problem, and an agent that keeps installing runtimes is an afternoon lost.

The documentation set

How to use it

An agent loads SKILL.md and follows the workflow: identify the tool, find the bottle, check compatibility, read the log and apply the fix from common-fixes.md. A human follows the same order as a checklist in the README: check the tool overview, find the prefix, check compatibility on WineHQ AppDB or the CrossOver compatibility list, follow the debugging guide and then check common fixes.

When to use it, when not to

Use it when a Windows app fails on a Mac and you want the diagnosis done in the right order, when you do not know which of the six tools the machine has, or when the failure needs a log read rather than a setting guessed.

Do not use it expecting a guarantee: the README is a knowledge base and workflow, and compatibility changes with every Wine release, GPU driver and macOS update. And do not use it on a kernel anti-cheat case as if it were a runtime problem — the README names anti-cheat as a hard blocker rather than a fixable one.

Sources

1. Wine macOS AI Runner — repository — purpose, tool table, the four questions, prefix locations, Apple Silicon notes, capabilities and documentation set quoted above.
2. README.md — skill entry point, quick start, core concepts, debugging commands.

Project page: Wine macOS AI Runner

The README credits WineHQ AppDB and the CrossOver compatibility list as the places to check a known recipe. The repository is MIT-licensed.

FAQ

Does the skill replace Wine? No. It is a knowledge base and workflow for diagnosing Windows software on macOS across Wine-based compatibility layers.

Which tools does it cover? CrossOver, vanilla Wine, Whisky, Kegworks and Wineskin, Bottles, and the Game Porting Toolkit.

Where do prefixes live? Each tool keeps its own location, documented in the README: CrossOver bottles and Whisky bottles under the user's Application Support folder, vanilla Wine under the home folder, and wrapper prefixes inside the .app bundle.

What is a hard blocker? Kernel anti-cheat, unsupported DRM and DirectX 12 gaps, which the README lists as blockers rather than fixable DLL problems.