Wine en macOS con agente de IA: skill de diagnóstico para apps Windows
Skill y conjunto de referencia para que Cursor, Claude Code o Codex diagnostiquen y corrijan software Windows en macOS en CrossOver, Whisky, Wineskin, Bottle…
On this page
Wine en macOS con agente de IA: skill de diagnóstico para apps Windows
TL;DR
- El repositorio es base de conocimiento y skill para que un agente de IA diagnostique y resuelva problemas al correr juegos, aplicaciones y software Windows en macOS — en cualquier capa de compatibilidad basada en Wine.
- Cubre CrossOver, Wine puro, Whisky, Kegworks y Wineskin, Bottles y el Game Porting Toolkit de Apple, con lo que cada uno hace mejor y cómo llega el agente a cada uno.
- Casi todo el diagnóstico se reduce a cuatro preguntas: qué prefijo usa la app, qué versión de Windows emula, qué DLLs y runtimes están instalados, y si el fallo es en instalación, arranque o ejecución.
- Trae flujo de trabajo, comparación de herramientas, ubicación de prefijos por herramienta, depuración con
WINEDEBUG, correcciones conwinetricksy una base de problemas comunes.
Qué es y para quién
Wine macOS AI Runner es una skill y un conjunto de referencia para agentes de IA — Cursor, Claude Code, Codex, GitHub Copilot, Windsurf y los demás — más documentación para personas.
Es para quien tiene un programa de Windows que "debería funcionar" en el Mac y no funciona, y para el agente que tiene que ayudar a esa persona. El encuadre del README es la parte útil: no es solo Wine. El panorama en macOS son seis herramientas que se solapan, y el trabajo de la skill es identificar cuál tiene la persona antes de diagnosticar nada.
Las herramientas que cubre
| Herramienta | Tipo | Mejor para |
|---|---|---|
| CrossOver (CodeWeavers) | GUI y CLI de pago | usuario no técnico, instalación de un clic, soporte oficial |
| Wine (puro) | CLI gratis por Homebrew o MacPorts | usuario avanzado, control máximo, automatización |
| Whisky | GUI gratis, Apple Silicon primero | juegos en Mac serie M, Game Porting Toolkit |
| Kegworks y Wineskin | constructor de wrapper gratis | distribuir una app como bundle .app nativo |
| Bottles | GUI gratis, Linux y Flatpak | gestión de prefijos multiplataforma |
| Game Porting Toolkit | toolkit de desarrollador de Apple | traducción Direct3D a Metal, port de juegos |
Las cuatro preguntas
El README reduce casi todo el diagnóstico a cuatro:
- ¿En qué prefijo o bottle está instalada la app?
- ¿Qué versión de Windows emula ese prefijo — 7, 10 u 11?
- ¿Qué DLLs y runtimes están instalados — DirectX, .NET, VCRedist, DXVK?
- ¿El fallo es en instalación, arranque o ejecución?
Esa reducción es la razón por la que la skill le sirve a un agente: la primera pregunta no es "qué flag le paso a Wine", es "dónde está el prefijo", y un agente que adivina sin localizar el prefijo cambia ajustes en el bottle equivocado.
El README también lista dónde están los prefijos: bottles de CrossOver en ~/Library/Application Support/CrossOver/Bottles/<BottleName>/, Wine puro en ~/.wine/ o en el nuevo valor por defecto de Homebrew, Whisky en su carpeta Bottles/<uuid>/, y el wrapper de Kegworks o Wineskin dentro de /Applications/YourApp.app/Contents/Resources/.
Apple Silicon e Intel
| Arquitectura | Cómo corre la app Windows | Nota |
|---|---|---|
| Apple Silicon (arm64) | x86_64 por Wine más Rosetta 2 | se prefiere la ruta DXVK/MoltenVK a Metal, con cerca de 15–30% de sobrecarga |
| Intel (x86_64) | ejecución x86_64 nativa | mejor compatibilidad, driver de GPU limitado en Mac antiguo |
La cifra de sobrecarga es una nota de rendimiento, no una medición que puedas asumir para un juego concreto.
Qué puede hacer el agente
El README lista las capacidades: identificar qué herramienta tiene la persona, localizar el bottle o prefijo correcto, consultar una receta conocida en WineHQ AppDB o en la compatibilidad de CrossOver, aplicar la versión de Windows con overrides de DLL y ajustes de DXVK o vkd3d, leer e interpretar los logs de WINEDEBUG con +loaddll,+seh,+module, corregir DLL faltantes con winetricks y d3dx9, vcrun2019, dotnet48 y dxvk, diagnosticar pantalla negra, cuelgues, audio y mandos, e identificar bloqueos duros como anti-cheat de kernel, DRM no soportado y huecos de DirectX 12.
La última categoría es la honesta. Un anti-cheat de kernel que se niega a correr no es un problema de DLL, y un agente que sigue instalando runtimes pierde la tarde.
El conjunto de documentación
| Documento | Qué trae |
|---|---|
SKILL.md | skill principal: flujo, árbol de decisión, lógica de diagnóstico |
references/tools-overview.md | comparación detallada de todas las herramientas en macOS |
references/configuration.md | versión de Windows, overrides de DLL, ajustes de registro, DXVK y vkd3d |
references/debugging-and-logs.md | flujos de depuración, análisis de logs WINEDEBUG, patrones de error comunes |
references/cli-reference.md | wine, winecfg, winetricks, CLI de CrossOver, wineserver |
references/common-fixes.md | base de problemas: DLL faltantes, pantallas negras, audio, mandos, anti-cheat |
Cómo usarlo
El agente carga SKILL.md y sigue el flujo: identifica la herramienta, encuentra el bottle, comprueba compatibilidad, lee el log y aplica la corrección de common-fixes.md. La persona sigue el mismo orden como lista en el README: panorama de herramientas, ubicación del prefijo, compatibilidad en WineHQ AppDB o en la lista de CrossOver, guía de depuración y correcciones comunes.
Cuándo usarlo, cuándo no
Úsalo cuando una app de Windows falla en el Mac y quieres el diagnóstico en el orden correcto, cuando no sabes cuál de las seis herramientas tiene la máquina, o cuando el fallo necesita lectura de log en vez de un flag adivinado.
No lo uses esperando una garantía: el README es base de conocimiento y flujo, y la compatibilidad cambia con cada versión de Wine, driver de GPU y actualización de macOS. Y no lo uses en un caso de anti-cheat de kernel como si fuera un problema de runtime — el README nombra el anti-cheat como bloqueo duro y no como algo corregible.
Sources
- Wine macOS AI Runner — repositorio — propósito, tabla de herramientas, las cuatro preguntas, ubicaciones de prefijos, notas de Apple Silicon, capacidades y conjunto de documentación citados arriba.
- README.md — entrada de la skill, inicio rápido, conceptos centrales, comandos de depuración.
Página del proyecto: Wine macOS AI Runner
El README indica WineHQ AppDB y la lista de compatibilidad de CrossOver como los lugares para consultar una receta conocida. El repositorio tiene licencia MIT.
FAQ
¿La skill sustituye a Wine? No. Es base de conocimiento y flujo para diagnosticar software Windows en macOS dentro de una capa de compatibilidad basada en Wine.
¿Qué herramientas cubre? CrossOver, Wine puro, Whisky, Kegworks y Wineskin, Bottles, y el Game Porting Toolkit.
¿Dónde están los prefijos? Cada herramienta tiene su ubicación, documentada en el README: bottles de CrossOver y de Whisky en Application Support, Wine puro en la carpeta home, y el wrapper dentro del bundle .app.
¿Qué es un bloqueo duro? Anti-cheat de kernel, DRM no soportado y huecos de DirectX 12, que el README lista como bloqueo y no como problema de DLL corregible.