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 () o exporta una vez. Instala el extra: .

# 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-...

El repositorio es opcional: pásalo posicionalmente o con -gr/--github-repo, proporciona una guía con -s/--step-by-step, o ambos. Al menos uno es requerido. Solo con una guía, no se clona ningún repositorio — la guía debe ser autocontenida (instalar un paquete publicado, o clonar lo que necesite como un paso explícito); la reproducción en contenedor limpio aún verifica cada comando.

Las salidas se guardan en runs/<run-id>/: tutorial.md, step_by_step.md, troubleshooting.md, commands.sh, demo.tape, demo.mp4, demo.gif, además de manifest.json con los estados de las etapas y el costo total.

GitHub Action — verifica tu README en CI

Obtén una X roja cuando tu README deje de funcionar. La acción compuesta raíz del repositorio instala readme2demo desde su propio checkout fijado, construye la imagen del sandbox, ejecuta el pipeline completo contra la URL de tu repositorio y hace fallar la comprobación cuando la reproducción en contenedor limpio no pasa:

name: readme-check
on:
  push:
    branches: [main]        # modo url prueba HEAD de la rama por defecto — ver advertencia abajo
    paths: ["README.md"]
  schedule:
    - cron: "0 6 * * 1"     # semanal: detectar cambios en el mundo bajo un README sin cambios

permissions:
  contents: read

jobs:
  verify-readme:
    runs-on: ubuntu-latest
    steps:
      - uses: alphacrack/readme2demo@main   # fijar una etiqueta o SHA una vez publicado
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          skip-video: "true"

⚠ Solo modo URL — esto aún NO verifica cabezas de PR. La acción clona el HEAD de la rama remota por defecto de repo-url (por defecto: el repositorio que ejecuta el workflow); la ingesta acepta solo URLs https, --depth 1, sin fijar ref. En pull_request probaría el README de la rama base — no el del PR — así que no lo conectes a PRs esperando un veredicto previo a la fusión. Hasta que llegue #74 (ingesta por ruta local), on: push a la rama por defecto y un cron son los disparadores honestos; una entrada repo-path para verificación real de cabezas de PR llegará con ella.

Costo: cada ejecución gasta dinero real del agente en tu ANTHROPIC_API_KEY — típicamente unos pocos dólares, con un tope máximo fijado por budget-usd (por defecto "5"; la ejecución aborta si se excede). El filtro paths: más un cron mantienen el gasto proporcional a los cambios del README, y skip-video: "true" reduce el tiempo de ejecución (el renderizado tampoco cuesta dinero de API de todas formas).

La comprobación falla de dos formas distinguibles, nombradas en el registro del paso: README roto (pipeline completado, reproducción en sala limpia fallida — detectado mediante readme2demo report --json, porque readme2demo run deliberadamente sale con 0 en una ejecución completada pero no verificada) y infra de acción rota (salida de pipeline distinta de cero: preflight, presupuesto, Docker). Salidas: verified ("true"/"false") y run-dir; tutorial.md, step_by_step.md, verify.log (y demo.gif cuando el video está activado) se suben como el artefacto readme2demo-run.

step_by_step.md — la fuente del video

El video demo siempre se construye a partir de step_by_step.md: sus pasos se analizan, y cada comando seguro para demo y fundamentado se convierte en un comando escrito en el video con el título del paso mostrado como comentario en pantalla. Tres formas de llegar a existir, en orden de prioridad:

1. Tú pasas uno: readme2demo run <url> -s my_guide.md — se inyecta en el clon como la guía autorizada; el planificador y el agente la siguen, el video la reproduce. El <url> es opcional aquí: readme2demo run -s my_guide.md ejecuta solo guía contra un sandbox vacío.
2. El repositorio incluye uno (step_by_step.md / step-by-step.md en la raíz o docs/, cualquier mayúscula/minúscula): mismo tratamiento, automáticamente.
3. Ninguno existe: el pipeline genera un step_by_step.md detallado — cada comando del commands.sh verificado como un paso numerado con salidas reales capturadas — luego construye el video a partir de él. Listo para contribuir de vuelta al repositorio.

Los pasos de configuración (clonaciones, instalaciones, compilaciones) se documentan en la guía pero se mantienen fuera del video — se reproduce contra el árbol de trabajo ya verificado y construido, mostrando el resultado.

Cada tutorial lleva una insignia de verificación: ✅ Verificado el <fecha> · imagen <digest> · commit <sha> — o un fuerte ⚠ NO VERIFICADO si la reproducción no pasó. La salida no verificada nunca se publica en silencio.

Configuración

Banderas CLI > readme2demo.toml > valores predeterminados:

engine = "claude-code"      # o "openhands"
model = "claude-sonnet-5"   # pases de planificador/destilador/tutorial
max_turns = 60
budget_usd = 5.0
base_image = "readme2demo/base:latest"
skip_video = false

Desarrollo

python -m pytest tests/ -q            # 175 pruebas unitarias, no necesita docker/red
ruff check src/ tests/               # lint de corrección (coincide con CI)
python -m pytest -m integration      # requiere docker + claves API (ninguna aún)

Modelo de seguridad

Los READMEs son código no confiable. El agente se ejecuta dentro de un contenedor endurecido (cap-drop ALL, no-new-privileges, límites de memoria/CPU/pids, no root) — ese contenedor es el límite de permisos. Compensación conocida de MVP: la clave API entra al sandbox; usa una clave dedicada de bajo límite. Se planea un proxy de egreso de inyección de claves del lado del host (Hito 4).

Modelo de amenazas completo y reporte de vulnerabilidades privadas: SECURITY.md.

Proyecto y comunidad

• Ejemplos — salida verificada comprometida como prueba
• Hoja de ruta — hacia dónde se dirige esto (incluyendo la dirección exploratoria alojada/SaaS)
• Contribuir — la única regla no negociable, y cómo configurarse
• Política de seguridad · Código de conducta
• Arquitectura — límites de etapas y diagramas

Licencia MIT. El CLI y el pipeline de verificación son, y seguirán siendo, gratuitos y de código abierto.

Contribuidores

¡Un enorme agradecimiento a todos los que han contribuido a readme2demo!