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 (--gemini gemini-3.5-flash) o esporta GEMINI_MODEL una volta. Installa l'extra: pip install 'readme2demo[gemini]'.
  • OpenAI (--openai [modello]): stessa forma di Gemini — una singola OPENAI_API_KEY alimenta i passaggi e l'agente OpenHands, nessun nome di modello è predefinito (--openai gpt-5.1 o esporta OPENAI_MODEL). Installa l'extra: pip install 'readme2demo[openai]'.
• Opzionale: LLM_API_KEY + LLM_MODEL per --engine openhands (sperimentale) con qualsiasi altro provider litellm — i preset sopra li compilano automaticamente

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