alphacrack/readme2demoTutoriales verificados y videos de demostración de tu README. Un agente de IA lo ejecuta en un sandbox Docker reforzado y lo reproduce en un contenedor nuevo antes de publicar cualquier cosa.
# readme2demo — tutoriales verificados y videos demo desde tu README
[](https://github.com/alphacrack/readme2demo/actions/workflows/ci.yml)
[](https://github.com/alphacrack/readme2demo/blob/main/LICENSE)
[](https://github.com/alphacrack/readme2demo/blob/main/pyproject.toml)
<!-- HERO:START — scripts/self-demo.sh rewrites this block with a fresh self-run.
Run it locally (needs Docker + VHS + a model credential):
./scripts/self-demo.sh
It runs readme2demo on this very repo, following docs/step-by-step.md,
and drops the verified demo.gif in right here. -->
[](https://github.com/alphacrack/readme2demo/tree/main/examples/readme2demo)
<sub>▶ 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 <a href="https://github.com/alphacrack/readme2demo/blob/main/examples/readme2demo">examples/readme2demo</a> · ejecuta contra otro proyecto en <a href="https://github.com/alphacrack/readme2demo/blob/main/examples/toolhive">examples/toolhive</a>.</sub>
<!-- HERO:END -->
**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](https://github.com/alphacrack/readme2demo/tree/main/examples) — 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](https://github.com/alphacrack/readme2demo/blob/main/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](https://github.com/alphacrack/readme2demo/blob/main/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
```bash
# 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
```bash
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
```bash
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**:
```yaml
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](https://github.com/alphacrack/readme2demo/issues/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:
```toml
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
```bash
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](https://github.com/alphacrack/readme2demo/blob/main/SECURITY.md).
## Proyecto y comunidad
- [Ejemplos](https://github.com/alphacrack/readme2demo/tree/main/examples) — salida verificada comprometida como prueba
- [Hoja de ruta](https://github.com/alphacrack/readme2demo/blob/main/ROADMAP.md) — hacia dónde se dirige esto (incluyendo la dirección exploratoria alojada/SaaS)
- [Contribuir](https://github.com/alphacrack/readme2demo/blob/main/CONTRIBUTING.md) — la única regla no negociable, y cómo configurarse
- [Política de seguridad](https://github.com/alphacrack/readme2demo/blob/main/SECURITY.md) · [Código de conducta](https://github.com/alphacrack/readme2demo/blob/main/CODE_OF_CONDUCT.md)
- [Arquitectura](https://github.com/alphacrack/readme2demo/blob/main/architecture/README.md) — 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!
[](https://github.com/alphacrack/readme2demo/graphs/contributors)
<a href="https://github.com/alphacrack/readme2demo/graphs/contributors">
<img src="https://contrib.rocks/image?repo=alphacrack/readme2demo" alt="Contributors" />
</a>