readme2demo — tutorial verificati e video demo dal tuo README

_{▶ readme2demo che genera il proprio tutorial: un agente AI esegue il README di questo repository in una sandbox, un contenitore fresco riproduce ogni passaggio, quindi viene renderizzato il demo. Output completo dell'auto-esecuzione in examples/readme2demo · eseguito su un altro progetto in examples/toolhive.}

Generatore di tutorial e video demo verificati dall'AI. Puntalo a un repository. Un agente AI legge il README e lo esegue effettivamente all'interno di una sandbox Docker blindata. Solo dopo che una riproduzione in ambiente pulito ha successo, genera un video demo (VHS) e pubblica il tutorial, la guida passo-passo e il documento di risoluzione dei problemi.

Il valore non è "l'AI scrive un tutorial" — è che il tutorial è stato eseguito, due volte, prima che tu lo vedessi.

Vedilo in azione: esplora esempi di esecuzioni verificate — tutorial reali, guide passo-passo e video demo, ciascuno riprodotto indipendentemente in un contenitore pulito prima della pubblicazione.

Come funziona

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

Vedi architecture/README.md per l'architettura completa.

Requisiti

• Python ≥ 3.10, Docker
• Autenticazione, una tra:
  • La tua sottoscrizione Claude (nessuna chiave API): un'installazione locale di Claude Code. I passaggi di pianificatore/distillatore/tutorial vengono eseguiti sulla tua sottoscrizione tramite --llm-backend claude-cli (claude -p), e l'agente nella sandbox si autentica con CLAUDE_CODE_OAUTH_TOKEN (creane uno: claude setup-token). Completamente supportato per esecuzioni self-hosted, singolo operatore sui tuoi repository — i piani Pro/Max includono un credito SDK agente mensile che copre claude -p.
  • ANTHROPIC_API_KEY — fatturazione API a consumo; ottimale per scala e concorrenza, e richiesto se ospiti readme2demo come servizio per altri (secondo i termini di Anthropic, l'autenticazione tramite sottoscrizione potrebbe non alimentare un prodotto multi-tenant — vedi ROADMAP.md). Aggiungi --anthropic [modello] per eseguire l'agente in sandbox sul motore OpenHands con un modello Claude invece di claude-code.
  • Google Gemini (--gemini [modello]): una singola GEMINI_API_KEY esegue l'intera sessione senza Claude — i passaggi di pianificatore/distillatore/tutorial usano Gemini e l'agente in sandbox viene eseguito sul motore OpenHands (anch'esso su Gemini). Nessun nome di modello è predefinito (Google ritira quelli vecchi con un 404 duro): specifica il modello per esecuzione () o esporta una volta. Installa l'extra: .

# run on your Claude subscription (no API key) — supported for self-hosted runs
claude setup-token        # interactive: approve in browser, then COPY the
                          # sk-ant-oat01-... token it prints (do NOT use $(...))
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
readme2demo run <repo-url> --llm-backend claude-cli

# run on metered API billing (scale, concurrency, or hosting for others)
export ANTHROPIC_API_KEY=sk-ant-...
readme2demo run <repo-url>              # --llm-backend auto picks api

# run the whole session on Google Gemini (OpenHands agent + Gemini passes)
pip install 'readme2demo[gemini]'
docker build -t readme2demo/openhands:latest images/openhands   # one-time: OpenHands sandbox image
export GEMINI_API_KEY=...
readme2demo run <repo-url> --gemini gemini-3.5-flash   # model named per run
export GEMINI_MODEL=gemini-3.5-flash                   # ...or set once, then:
readme2demo run <repo-url> --gemini                    # bare flag reads GEMINI_MODEL

# run the whole session on OpenAI (OpenHands agent + OpenAI passes)
pip install 'readme2demo[openai]'
export OPENAI_API_KEY=sk-...
readme2demo run <repo-url> --openai gpt-5.1            # or export OPENAI_MODEL once

# run the OpenHands agent with a Claude model on API billing
export ANTHROPIC_API_KEY=sk-ant-...
readme2demo run <repo-url> --anthropic                 # uses the config model by default

Installazione

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

Utilizzo

readme2demo run https://github.com/example/tool
readme2demo run -gr https://github.com/example/tool             # same, via the flag
readme2demo run -s my_guide.md                                  # guide-only: no repo, your guide is self-contained
readme2demo run -gr https://github.com/example/tool -s my_guide.md   # both: your guide drives everything
readme2demo run https://github.com/example/tool --gemini gemini-3.5-flash  # run on Google Gemini (needs GEMINI_API_KEY; uses the OpenHands agent; bare --gemini reads GEMINI_MODEL)
readme2demo run https://github.com/example/tool --openai gpt-5.1           # run on OpenAI (needs OPENAI_API_KEY; uses the OpenHands agent; bare --openai reads OPENAI_MODEL)
readme2demo run https://github.com/example/tool --anthropic                # OpenHands agent with a Claude model on ANTHROPIC_API_KEY
readme2demo run https://github.com/example/tool --allow-docker-socket  # for tools that manage containers (SECURITY TRADEOFF: pierces sandbox isolation — trusted repos only)
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-...

Il repository è opzionale: passalo posizionalmente o con -gr/--github-repo, fornisci una guida con -s/--step-by-step, o entrambi. Almeno uno è richiesto. Con una sola guida, nessun repository viene clonato — la guida deve essere autosufficiente (installare un pacchetto pubblicato, o clonare ciò di cui ha bisogno come passaggio esplicito); la riproduzione in contenitore fresco verifica comunque ogni comando.

Gli output vengono salvati in runs/<run-id>/: tutorial.md, step_by_step.md, troubleshooting.md, commands.sh, demo.tape, demo.mp4, demo.gif, più manifest.json con stati delle fasi e costo totale.

GitHub Action — verifica il tuo README in CI

Ottieni una X rossa quando il tuo README smette di funzionare. L'azione composita alla radice del repository installa readme2demo dal suo checkout fissato, costruisce l'immagine sandbox, esegue l'intera pipeline contro l'URL del tuo repository, e fallisce il controllo quando la riproduzione in contenitore fresco non passa:

name: readme-check
on:
  push:
    branches: [main]        # url mode tests the default branch HEAD — see the caveat below
    paths: ["README.md"]
  schedule:
    - cron: "0 6 * * 1"     # weekly: catch the world changing under an unchanged README

permissions:
  contents: read

jobs:
  verify-readme:
    runs-on: ubuntu-latest
    steps:
      - uses: alphacrack/readme2demo@main   # pin a tag or SHA once released
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          skip-video: "true"

⚠ Solo modalità URL — questo NON verifica ancora le PR head. L'azione clona il remoto HEAD del branch predefinito di repo-url (default: il repository che esegue il workflow); l'ingestione accetta solo URL https, --depth 1, nessun pinning di ref. Su pull_request testa il README del branch base — non quello della PR — quindi non collegarlo a PR aspettandoti un verdetto pre-merge. Fino a quando #74 (ingestione su percorso locale) non arriverà, on: push sul branch predefinito e un cron sono i trigger onesti; un input repo-path per la vera verifica della testa della PR arriverà con essa.

Costo: ogni esecuzione spende soldi reali dell'agente sulla tua ANTHROPIC_API_KEY — tipicamente qualche dollaro, con un tetto massimo da budget-usd (default "5"; l'esecuzione viene interrotta se superato). Il filtro paths: insieme a un cron mantiene la spesa proporzionale ai cambiamenti del README, e skip-video: "true" riduce il tempo reale (il render non costa soldi API in ogni caso).

Il controllo fallisce in due modi distinguibili, nominati nel log del passo: README rotto (pipeline completata, riproduzione in ambiente pulito fallita — rilevato tramite readme2demo report --json, perché readme2demo run esce deliberatamente con 0 su un'esecuzione completata ma non verificata) e infrastruttura azione rotta (uscita pipeline non zero: preflight, budget, Docker). Output: verified ("true"/"false") e run-dir; tutorial.md, step_by_step.md, verify.log (e demo.gif quando il video è attivo) vengono caricati come artefatto readme2demo-run.

step_by_step.md — la fonte del video

Il video demo è sempre costruito da step_by_step.md: i suoi passaggi vengono analizzati e ogni comando sicuro per demo e fondato diventa un comando digitato nel video con il titolo del passaggio mostrato come commento sullo schermo. Tre modi in cui viene creato, in ordine di priorità:

1. Ne fornisci uno: readme2demo run <url> -s my_guide.md — iniettato nel clone come guida autorevole; pianificatore e agente lo seguono, il video lo riproduce. L'<url> è opzionale qui: readme2demo run -s my_guide.md esegue solo guida in una sandbox vuota.
2. Il repository ne fornisce uno (step_by_step.md / step-by-step.md alla radice o in docs/, qualsiasi maiuscolo/minuscolo): stesso trattamento, automaticamente.
3. Nessuno esiste: la pipeline genera un step_by_step.md dettagliato — ogni comando dal commands.sh verificato come passaggio numerato con output reali catturati — poi costruisce il video da esso. Pronto per essere contribuito al repository.

I passaggi di configurazione (clonazioni, installazioni, build) sono documentati nella guida ma tenuti fuori dal video — viene riprodotto sull'albero di lavoro verificato e già costruito, mostrando il risultato.

Ogni tutorial porta un badge di verifica: ✅ Verificato il <data> · immagine <digest> · commit <sha> — o un sonoro ⚠ NON VERIFICATO se la riproduzione non è passata. L'output non verificato non viene mai pubblicato silenziosamente.

Configurazione

Flags CLI > readme2demo.toml > default:

engine = "claude-code"      # or "openhands"
model = "claude-sonnet-5"   # planner/distiller/tutorial passes
max_turns = 60
budget_usd = 5.0
base_image = "readme2demo/base:latest"
skip_video = false

Sviluppo

python -m pytest tests/ -q            # 175 unit tests, no docker/network needed
ruff check src/ tests/               # correctness lint (matches CI)
python -m pytest -m integration      # requires docker + API keys (none yet)

Modello di sicurezza

I README sono codice non fidato. L'agente viene eseguito all'interno di un contenitore blindato (cap-drop ALL, no-new-privileges, limiti memory/cpu/pids, non-root) — quel contenitore è il confine di autorizzazione. Compromesso noto MVP: la chiave API entra nella sandbox; usa una chiave dedicata con limiti bassi. Un proxy di uscita per iniezione di chiavi lato host è pianificato (Milestone 4).

Modello di minaccia completo e segnalazione di vulnerabilità private: SECURITY.md.

Progetto e community

• Esempi — output verificato impegnato come prova
• Roadmap — dove sta andando (inclusa la direzione esplorativa hosted/SaaS)
• Contribuire — l'unica regola non negoziabile e come configurarsi
• Politica di sicurezza · Codice di condotta
• Architettura — confini e diagrammi delle fasi

Licenza MIT. La CLI e la pipeline di verifica sono e rimarranno gratuiti e open source.

Collaboratori

Un enorme ringraziamento a tutti coloro che hanno contribuito a readme2demo!