# Wine macOS AI Runner - Run Windows Apps/Games on macOS Using AI Agents

[![GitHub stars](https://img.shields.io/github/stars/artificialguybr/wine-macos-ai-runner?style=social)](https://github.com/artificialguybr/wine-macos-ai-runner)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Platform: macOS](https://img.shields.io/badge/Platform-macOS-lightgrey)](https://www.apple.com/macos/)
[![AI Agents](https://img.shields.io/badge/AI%20Agents-Cursor%2C%20Claude%20Code%2C%20Codex-blue)](https://github.com/artificialguybr/wine-macos-ai-runner)

> **Complete skill & reference for AI agents to run ANY Windows software on macOS** — Not just Wine! Supports CrossOver, Whisky, Kegworks, Wineskin, Bottles, Game Porting Toolkit, and all Wine-based compatibility layers.

## 🎯 Purpose

This repository provides a **complete knowledge base and skill set for AI agents** (Cursor, Claude Code, Codex, GitHub Copilot, Windsurf, etc.) to diagnose and solve problems when running Windows games, applications, and software on macOS through **any Wine-based compatibility layer**.

## 🎮 What This Covers — ALL macOS Windows Compatibility Tools

| Tool | Type | Best For | AI Agent Support |
|------|------|----------|------------------|
| **CrossOver** (CodeWeavers) | Paid GUI + CLI | Non-technical users, one-click installs, official support | ✅ Full CLI via `CX_BOTTLE` |
| **Wine (vanilla)** | Free CLI (Homebrew/MacPorts) | Power users, max control, automation | ✅ Native `wine`, `winecfg`, `winetricks` |
| **Whisky** | Free GUI (Apple Silicon-first) | Gaming on M-series Macs, Game Porting Toolkit | ✅ Bottles are real Wine prefixes |
| **Kegworks / Wineskin** | Free wrapper builder | Distributing single apps as native .app bundles | ✅ Prefix accessible via `WINEPREFIX` |
| **Bottles** (Linux/Flatpak) | Free GUI | Cross-platform prefix management | ✅ Standard Wine prefix structure |
| **Game Porting Toolkit (GPTK)** | Apple's dev toolkit | Direct3D→Metal translation, game porting | ✅ Underlies Whisky/CrossOver |

## 📚 Documentation

| Document | Description |
|----------|-------------|
| **[SKILL.md](SKILL.md)** | **Main skill for AI agents** — Complete workflow, decision tree, and troubleshooting logic |
| **[references/tools-overview.md](references/tools-overview.md)** | Detailed comparison of all Wine-based tools on macOS |
| **[references/configuration.md](references/configuration.md)** | Windows version selection, DLL overrides, registry tweaks, DXVK/vkd3d |
| **[references/debugging-and-logs.md](references/debugging-and-logs.md)** | Debugging workflows, log analysis (WINEDEBUG), common error patterns |
| **[references/cli-reference.md](references/cli-reference.md)** | Complete CLI reference: `wine`, `winecfg`, `winetricks`, CrossOver CLI, `wineserver` |
| **[references/common-fixes.md](references/common-fixes.md)** | Database of common issues: missing DLLs, black screens, audio, controllers, anti-cheat |

## 🚀 Quick Start for AI Agents

If you're an **AI agent** (Cursor, Claude Code, Codex, GitHub Copilot, Windsurf, etc.), load this skill:

```
The skill is defined in SKILL.md — it contains the complete workflow
for diagnosing and fixing Windows-on-macOS issues across ALL tools.
```

**Key capabilities this skill gives AI agents:**
- Identify which tool the user has (CrossOver, Wine, Whisky, Kegworks, etc.)
- Locate the correct bottle/prefix automatically
- Check WineHQ AppDB / CrossOver Compatibility for known recipes
- Apply correct Windows version, DLL overrides, DXVK/vkd3d settings
- Read and interpret `WINEDEBUG` logs (`+loaddll,+seh,+module`)
- Fix missing DLLs via `winetricks` (d3dx9, vcrun2019, dotnet48, dxvk)
- Diagnose black screens, crashes, audio issues, controller problems
- Identify hard blockers (kernel anti-cheat, unsupported DRM, DX12 gaps)

## 🎯 For Human Users

1. **Identify your tool** — Check [tools-overview.md](references/tools-overview.md)
2. **Find your bottle/prefix** — See [configuration.md](references/configuration.md)
3. **Check compatibility** — Search [WineHQ AppDB](https://appdb.winehq.org) or [CrossOver Compatibility](https://www.codeweavers.com/compatibility)
4. **Follow debugging guide** — See [debugging-and-logs.md](references/debugging-and-logs.md)
5. **Check common fixes** — See [common-fixes.md](references/common-fixes.md)

## 🏗️ Core Concepts

### The "Bottle" / "Prefix" Concept
Every Wine-based tool creates a **Wine prefix** — a fake `C:\` drive that's just a directory on macOS. Almost all troubleshooting reduces to:
1. Which prefix/bottle is the app installed in?
2. What Windows version is that prefix emulating? (Win7, Win10, Win11)
3. What DLLs/runtimes are installed? (DirectX, .NET, VCRedist, DXVK)
4. Is the failure at install, launch, or runtime?

**Common prefix locations:**
```bash
# CrossOver
~/Library/Application Support/CrossOver/Bottles/<BottleName>/

# Vanilla Wine
~/.wine/                    # legacy default
~/Library/Application Support/Wine/  # newer Homebrew default

# Whisky
~/Library/Application Support/Whisky/Bottles/<uuid>/

# Kegworks/Wineskin wrapper
/Applications/YourApp.app/Contents/Resources/
```

### Apple Silicon (M1/M2/M3/M4) vs Intel
| Architecture | How Windows Apps Run | Performance Notes |
|--------------|---------------------|-------------------|
| **Apple Silicon (arm64)** | x86_64 → ARM translation via Wine + Rosetta 2 | DXVK/MoltenVK→Metal path preferred; expect ~15-30% overhead |
| **Intel (x86_64)** | Native x86_64 execution | Better compatibility; GPU driver limited on older Macs |

## 🔍 Quick Debugging Commands

```bash
# Find ALL bottles/prefixes on this Mac
find ~/Library/Application\ Support -maxdepth 3 -iname "system.reg" 2>/dev/null

# Run with debug logging (vanilla Wine) — BEST for "why won't it launch"
WINEDEBUG=+loaddll,+seh,+module wine "/path/to/app.exe" > ~/Desktop/winelog.txt 2>&1

# Graphics/DirectX specific logging
WINEDEBUG=+d3d,+dxgi,+d3d11 wine "/path/to/app.exe" 2> ~/Desktop/gfx.log

# CrossOver CLI (use CrossOver's own wine binary + bottle env)
CX_BOTTLE="MyBottle" /Applications/CrossOver.app/Contents/SharedSupport/CrossOver/bin/wine "app.exe"

# Install common runtimes (run INSIDE the target prefix)
export WINEPREFIX=~/path/to/prefix
winetricks corefonts vcrun2019 dotnet48 d3dx9 dxvk

# Enable DXVK HUD for performance debugging
export DXVK_HUD=fps,frametimes,gpuload
wine "/path/to/app.exe"
```

## ⚠️ Hard Limitations — Be Honest With Users

**These CANNOT be fixed on ANY Wine-based layer:**

| Blocker | Examples | Why |
|---------|----------|-----|
| **Kernel-level anti-cheat** | Easy Anti-Cheat (kernel mode), BattlEye, Riot Vanguard | Requires real Windows kernel driver; Wine has no kernel mode |
| **Certain DRM** | Some Denuvo, SecuROM, StarForce | Kernel/low-level hooks Wine cannot replicate |
| **DirectX 12 features** | Ray tracing, mesh shaders, sampler feedback | DXVK/vkd3d-proton still catching up |
| **Windows kernel drivers** | Some hardware drivers, virtualization tools | No Windows kernel in Wine |

**Tell users plainly:** "This game has kernel-level anti-cheat (EAC/BattlEye/Vanguard) — it will NOT run on Wine/CrossOver/Whisky on macOS. No workaround exists."

## 📖 References

- [WineHQ AppDB](https://appdb.winehq.org) — Community compatibility database
- [CrossOver Compatibility Center](https://www.codeweavers.com/compatibility) — Official CodeWeavers database
- [WineHQ Wiki](https://wiki.winehq.org) — Official documentation
- [DXVK GitHub](https://github.com/doitsujin/dxvk) — D3D9/10/11 → Vulkan
- [VKD3D-Proton GitHub](https://github.com/HansKristian-Work/vkd3d-proton) — D3D12 → Vulkan
- [MoltenVK](https://github.com/KhronosGroup/MoltenVK) — Vulkan → Metal (macOS)
- [Game Porting Toolkit](https://developer.apple.com/game-porting-toolkit/) — Apple's D3D→Metal

## 📄 License

MIT License — Free to use, modify, and distribute.

---

**Built for AI agents to help users run Windows software on macOS — regardless of which compatibility layer they choose.**