readme2demo — tutoriales verificados y videos demo desde tu README

_{▶ readme2demo generando su propio tutorial: un agente de IA ejecuta el README de este repositorio en un sandbox, un contenedor nuevo reproduce cada paso, luego se renderiza el demo. Salida completa de auto-ejecución en examples/readme2demo · ejecuta contra otro proyecto en examples/toolhive.}

Generador de tutoriales y videos demo verificados por IA. Apúntalo a un repositorio. Un agente de IA lee el README y realmente lo ejecuta dentro de un sandbox Docker endurecido. Solo después de que una reproducción en entorno limpio pasa, se renderiza un video demo (VHS) y se publican el tutorial, la guía paso a paso y el documento de solución de problemas.

El valor no es "la IA escribe un tutorial" — es que el tutorial se ejecutó, dos veces, antes de que lo vieras.

Míralo en acción: explora ejemplos de ejecuciones verificadas — tutoriales reales, guías paso a paso y videos demo, cada uno reproducido de forma independiente en un contenedor limpio antes de publicarse.

Cómo funciona

repo URL → ingest/plan → agent run (in Docker) → normalize transcript
        → distill minimal path → VERIFY replay in fresh container
        → generate tutorial.md + troubleshooting.md → render VHS video

Consulta architecture/README.md para la arquitectura completa.

Requisitos

• Python ≥ 3.10, Docker
• Autenticación, una de:
  • Tu suscripción de Claude (sin clave API): una instalación local de Claude Code. Los pases del planificador/destilador/tutorial se ejecutan en tu suscripción mediante --llm-backend claude-cli (claude -p), y el agente dentro del sandbox se autentica con CLAUDE_CODE_OAUTH_TOKEN (crea uno: claude setup-token). Totalmente compatible para ejecuciones autoalojadas y de un solo operador contra tus propios repositorios — los planes Pro/Max incluyen un crédito mensual del SDK de Agent que cubre claude -p.
  • ANTHROPIC_API_KEY — facturación por API medida; mejor para escala y concurrencia, y requerido si alojas readme2demo como servicio para otros (según los términos de Anthropic, la autenticación por suscripción puede no alimentar un producto multiinquilino — consulta ROADMAP.md). Agrega --anthropic [model] para ejecutar el agente en sandbox en el motor OpenHands con un modelo Claude en lugar de claude-code.
  • Google Gemini (--gemini [model]): una sola GEMINI_API_KEY ejecuta toda la sesión fuera de Claude — los pases del planificador/destilador/tutorial usan Gemini y el agente en sandbox se ejecuta en el motor OpenHands (también en Gemini). No hay un nombre de modelo incorporado (Google retira los antiguos con un 404 duro): nómbralo por ejecución (--gemini gemini-3.5-flash) o exporta GEMINI_MODEL una vez. Instala el extra: pip install 'readme2demo[gemini]'.
  • OpenAI (--openai [model]): misma forma que Gemini — una sola OPENAI_API_KEY alimenta los pases y el agente OpenHands, no hay nombre de modelo incorporado (--openai gpt-5.1 o exporta OPENAI_MODEL). Instala el extra: pip install 'readme2demo[openai]'.
• Opcional: LLM_API_KEY + LLM_MODEL para --engine openhands (experimental) con cualquier otro proveedor de litellm — los presets anteriores los completan automáticamente

# ejecutar con tu suscripción de Claude (sin clave API) — compatible para ejecuciones autoalojadas
claude setup-token        # interactivo: aprueba en el navegador, luego COPIA el
                          # token sk-ant-oat01-... que imprime (NO uses $(...))
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
readme2demo run <repo-url> --llm-backend claude-cli

# ejecutar con facturación por API medida (escala, concurrencia, o alojamiento para otros)
export ANTHROPIC_API_KEY=sk-ant-...
readme2demo run <repo-url>              # --llm-backend auto picks api

# ejecutar toda la sesión en Google Gemini (agente OpenHands + pases Gemini)
pip install 'readme2demo[gemini]'
docker build -t readme2demo/openhands:latest images/openhands   # una vez: imagen del sandbox OpenHands
export GEMINI_API_KEY=...
readme2demo run <repo-url> --gemini gemini-3.5-flash   # modelo nombrado por ejecución
export GEMINI_MODEL=gemini-3.5-flash                   # ...o configúralo una vez, luego:
readme2demo run <repo-url> --gemini                    # bandera simple lee GEMINI_MODEL

# ejecutar toda la sesión en OpenAI (agente OpenHands + pases OpenAI)
pip install 'readme2demo[openai]'
export OPENAI_API_KEY=sk-...
readme2demo run <repo-url> --openai gpt-5.1            # o exporta OPENAI_MODEL una vez

# ejecutar el agente OpenHands con un modelo Claude mediante facturación por API
export ANTHROPIC_API_KEY=sk-ant-...
readme2demo run <repo-url> --anthropic                 # usa el modelo de configuración por defecto

Instalación

pip install -e ".[dev]"
docker build -t readme2demo/base:latest images/base/
docker build -t readme2demo/openhands:latest images/openhands/   # solo para --engine openhands / --gemini / --openai / --anthropic

Uso

readme2demo run https://github.com/example/tool
readme2demo run -gr https://github.com/example/tool             # igual, mediante la bandera
readme2demo run -s my_guide.md                                  # solo guía: sin repositorio, tu guía es autocontenida
readme2demo run -gr https://github.com/example/tool -s my_guide.md   # ambos: tu guía dirige todo
readme2demo run https://github.com/example/tool --gemini gemini-3.5-flash  # ejecutar en Google Gemini (necesita GEMINI_API_KEY; usa el agente OpenHands; --gemini simple lee GEMINI_MODEL)
readme2demo run https://github.com/example/tool --openai gpt-5.1           # ejecutar en OpenAI (necesita OPENAI_API_KEY; usa el agente OpenHands; --openai simple lee OPENAI_MODEL)
readme2demo run https://github.com/example/tool --anthropic                # agente OpenHands con un modelo Claude en ANTHROPIC_API_KEY
readme2demo run https://github.com/example/tool --allow-docker-socket  # para herramientas que gestionan contenedores (COMPENSACIÓN DE SEGURIDAD: rompe el aislamiento del sandbox — solo repositorios de confianza)
readme2demo run https://github.com/example/tool --skip-video --budget-usd 3
readme2demo resume runs/tool-20260702-... --from-stage render
readme2demo report runs/tool-20260702-...