Sky-Claw — AI-assisted Skyrim Mod Manager for Mod Organizer 2

Local AI-assisted Skyrim SE/AE mod management and automation for Mod Organizer 2 (MO2), LOOT, xEdit, FOMOD and Nexus Mods.

Sky-Claw is a local, AI-assisted control plane for Skyrim Special Edition and Anniversary Edition modding. It combines natural-language workflows with human approval gates, traceability and integrations around the existing Skyrim modding toolchain instead of replacing it with an unrestricted autonomous agent.

Audiencia: usuarios, operadores y contribuidores.

Estado: producto en desarrollo; las garantías por subsistema se detallan
en la documentación enlazada.

Fuentes canónicas: runtime, ADR vigentes, DEPLOYMENT.md y SECURITY.md.

Última verificación integral: 2026-07-25 sobre origin/main c6ab35e.

Sincronización DB/lifecycle: 2026-08-16 sobre main 7156718; no implica
reverificación integral del resto de claims del README.

Sincronización release/empaquetado: 2026-08-16 sobre main f6d502c;
limitada al estado público de los artefactos de v0.2.4.

Sincronización parcial xEdit LLM: 2026-09-04 sobre main 10354c2b (#548);
limitada a la frontera read-only de run_xedit_script. No implica reverificación
integral del resto del README.

🚀 Descripción

Sky-Claw es un plano de control local asistido por IA para gestionar mods de
Skyrim SE/AE a través de Mod Organizer 2 (MO2). Permite buscar, descargar,
instalar y analizar conflictos usando lenguaje natural, con locks, trazabilidad
y gates humanos en las operaciones que los requieren. Su norte es una
caja negra de vuelo, no un agente autónomo irrestricto.

Capacidades principales

Skyrim SE/AE + Mod Organizer 2: automatización orientada a perfiles y flujos de modding sobre MO2.
LOOT y xEdit: ejecución integrada para ordenar plugins y analizar o transformar datos del load order.
FOMOD y Nexus Mods: resolución de instaladores FOMOD y flujos de descarga controlados.
IA local o por API: proveedores Anthropic, OpenAI, DeepSeek y Ollama detrás de una interfaz unificada.
Human-in-the-loop (HITL): operaciones sensibles pueden requerir aprobación humana antes de ejecutarse.
GUI, CLI y Telegram: varias superficies de interacción sobre el mismo plano de control.

Novedades de la Versión Moderna:

Soporte Multi-LLM: Elegí entre Anthropic (Claude), OpenAI (GPT-4), DeepSeek o ejecución local con Ollama.
Interfaz Gráfica (GUI): Interfaz moderna basada en NiceGUI (web/escritorio) para una gestión visual.
Configuración TOML: Gestión simplificada en ~/.sky_claw/config.toml.
Asistente de Inicio: Configuración guiada automática con local_scripts/scripts/first_run.py.
Seguridad HITL: Aprobación interactiva en los handlers y rituales que
cablean un gate humano.
Community Shaders: Instalación opt-in de
Community Shaders y sus dependencias, con los requisitos del entorno verificados antes
de descargar nada.

🏗️ Arquitectura Moderna

Usuario (GUI / CLI / Telegram)
         |
    LLMRouter (Mensajería + Tool Dispatch)
         |
    LLMProvider (Interfaz Unificada)
    |-- AnthropicProvider
    |-- OpenAIProvider
    |-- DeepSeekProvider
    |-- OllamaProvider
         |
   AsyncToolRegistry
   |-- search_mod        -> AsyncModRegistry (SQLite)
   |-- check_load_order  -> MO2Controller (modlist.txt)
   |-- detect_conflicts  -> SQL JOIN sobre dependencias
   |-- run_loot_sort     -> VfsExecutionBroker -> worker LOOT bajo MO2/USVFS
   |-- run_xedit_script  -> xedit_readonly_tool (allowlist read-only + staging canónico) -> XEditRunner
   |-- download_mod      -> NexusDownloader + HITLGuard
         |
    MO2 Portable / Skyrim SE

La persistencia SQLite gestionada usa DatabaseLifecycleManager: los
consumidores lifecycle-backed mantienen operation() o transaction() durante
la unidad SQL completa. Obtener una conexión mediante get_connection() no
conserva por sí solo el boundary frente a un shutdown concurrente. Véase
Datos, persistencia y recuperación.

📦 Instalación

Sky-Claw incluye scripts automáticos para facilitar la instalación:

Clonar y Construir:

git clone https://github.com/FacundoSu1986/sky-claw.git
cd sky-claw
build.bat

Configurar:
Ejecutá el asistente para configurar tus API Keys y detectar tus rutas de MO2:
```
python local_scripts/scripts/first_run.py
```

🎮 Uso

Modo Gráfico (GUI)

python -m sky_claw --mode gui

Modo Telegram (HITL Interactivo)

python -m sky_claw --mode telegram

Modo Terminal (CLI)

python -m sky_claw --mode cli

🛡️ Seguridad Zero-Trust

Sky-Claw aplica una política de seguridad estricta:

NetworkGateway: Solo permite conexiones a dominios autorizados (*.nexusmods.com, api.telegram.org, openai.com, etc.).
HITLGuard: download_mod y los rituales que lo inyectan esperan una
decisión humana; una ruta sin ese wiring no hereda HITL automáticamente.
Sandboxing: Todas las operaciones de archivo están restringidas al directorio de MO2 y carpetas de instalación autorizadas.
xEdit del agente LLM read-only (#548): la tool run_xedit_script que expone el
agente sólo ejecuta una allowlist de scripts de diagnóstico bundleados read-only;
el schema y el runtime comparten esa política, un nombre desconocido falla cerrado
y se exige staging canónico antes de ejecutar. Esto no convierte en read-only a
todas las rutas internas de xEdit: los rituales/orquestador mutantes usan otra
frontera (ver fronteras de seguridad).

👨‍💻 Para Desarrolladores

Sky-Claw es un ecosistema asíncrono complejo. Si deseas contribuir, añadir nuevas herramientas o entender cómo funciona el orquestador por dentro, consulta la siguiente documentación:

Arquitectura del Sistema: Topología de capas, flujo de datos asíncrono y modelo de seguridad.
Guía de Contribución: Setup del entorno de desarrollo, flujo de trabajo TDD, convenciones de código y proceso de PRs.
Manual de Agentes y Tools: Tutorial para extender el sistema con nuevos Tool Runners y proveedores LLM.
SOP del Pipeline de Modding: Reglas de negocio inmutables para la orquestación de herramientas de Skyrim.
Portal de Documentación: Guías para usuarios, operadores, desarrolladores y agentes.
Fuentes de verdad: Precedencia para resolver contradicciones y DOCUMENTATION_DRIFT.

✅ Roadmap (Estado Actual)

Soporte Multi-LLM (OpenAI, Anthropic, DeepSeek, Ollama)
Interfaz Gráfica Moderna (NiceGUI)
Configuración centralizada TOML
Asistente interactivo de primera ejecución
HITL en handlers y rituales cableados a un gate humano
Base de datos async distribuida
Wrapper xEdit y LOOT headless
Parser y resolución FOMOD
Empaquetado .exe único publicado en v0.2.4 (firma, cold boot y smokes reales quedan fuera de esta verificación)

Acknowledgements

Sky-Claw incorporates architectural inspiration from
Hermes Agent by Nous Research,
particularly around LLM tool-calling protocols.

See THIRD_PARTY_NOTICES.md for details.

📄 Licencia

MIT