readme2demo — tutoriels vérifiés et vidéos de démonstration à partir de votre README

_{▶ readme2demo générant son propre tutoriel : un agent IA exécute ce README dans un bac à sable, un nouveau conteneur rejoue chaque étape, puis la démo est rendue. Sortie complète de l'auto-exécution dans examples/readme2demo · exécution sur un autre projet dans examples/toolhive.}

Générateur de tutoriel et de vidéo de démonstration vérifié par IA. Pointez-le vers un dépôt. Un agent IA lit le README et l'exécute réellement à l'intérieur d'un bac à sable Docker renforcé. Ce n'est qu'après une relecture en environnement vierge réussie qu'il génère une vidéo de démonstration (VHS) et publie le tutoriel, le guide pas à pas et le document de dépannage.

La valeur ne réside pas dans « l'IA qui écrit un tutoriel » — c'est que le tutoriel a été exécuté, deux fois, avant que vous ne le voyiez.

Voyez-le en action : parcourez les exemples d'exécutions vérifiées — de vrais tutoriels, guides pas à pas et vidéos de démonstration, chacun rejoué indépendamment dans un conteneur propre avant d'être publié.

Comment ça marche

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

Consultez architecture/README.md pour l'architecture complète.

Prérequis

• Python ≥ 3.10, Docker
• Authentification, l'une des suivantes :
  • Votre abonnement Claude (pas de clé API) : une installation locale de Claude Code. Les passes planificateur/condenseur/tutoriel s'exécutent sur votre abonnement via --llm-backend claude-cli (claude -p), et l'agent dans le bac à sable s'authentifie avec CLAUDE_CODE_OAUTH_TOKEN (créez-en un : claude setup-token). Entièrement pris en charge pour les exécutions auto-hébergées, mono-opérateur sur vos propres dépôts — les plans Pro/Max incluent un crédit mensuel Agent SDK qui couvre claude -p.
  • ANTHROPIC_API_KEY — facturation API à l'utilisation ; idéal pour le passage à l'échelle et la concurrence, et obligatoire si vous hébergez readme2demo en tant que service pour d'autres (selon les conditions d'Anthropic, l'authentification par abonnement peut ne pas alimenter un produit multi-locataire — voir ROADMAP.md). Ajoutez --anthropic [model] pour exécuter l'agent en bac à sable sur le moteur OpenHands avec un modèle Claude au lieu de claude-code.
  • Google Gemini (--gemini [model]) : une seule GEMINI_API_KEY exécute toute la session sans Claude — les passes planificateur/condenseur/tutoriel utilisent Gemini et l'agent en bac à sable tourne sur le moteur OpenHands (également sur Gemini). Aucun nom de modèle n'est intégré (Google retire les anciens avec une erreur 404 définitive) : nommez-le par exécution (--gemini gemini-3.5-flash) ou exportez GEMINI_MODEL une fois pour toutes. Installez l'extra : pip install 'readme2demo[gemini]'.
  • OpenAI (--openai [model]) : même structure que Gemini — une seule OPENAI_API_KEY alimente les passes et l'agent OpenHands, aucun nom de modèle n'est intégré (--openai gpt-5.1 ou exportez OPENAI_MODEL). Installez l'extra : pip install 'readme2demo[openai]'.
• Optionnel : LLM_API_KEY + LLM_MODEL pour --engine openhands (expérimental) avec tout autre fournisseur litellm — les préréglages ci-dessus les remplissent automatiquement

# exécution sur votre abonnement Claude (pas de clé API) — pris en charge pour les exécutions auto-hébergées
claude setup-token        # interactif : approuvez dans le navigateur, puis COPIEZ le
                          # token sk-ant-oat01-... qu'il affiche (n'utilisez PAS $(...))
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
readme2demo run <url-du-dépôt> --llm-backend claude-cli

# exécution sur facturation API à l'utilisation (passage à l'échelle, concurrence, hébergement pour d'autres)
export ANTHROPIC_API_KEY=sk-ant-...
readme2demo run <url-du-dépôt>              # --llm-backend auto choisit api

# exécution de toute la session sur Google Gemini (agent OpenHands + passes Gemini)
pip install 'readme2demo[gemini]'
docker build -t readme2demo/openhands:latest images/openhands   # une fois : image du bac à sable OpenHands
export GEMINI_API_KEY=...
readme2demo run <url-du-dépôt> --gemini gemini-3.5-flash   # modèle nommé par exécution
export GEMINI_MODEL=gemini-3.5-flash                   # ...ou défini une fois, puis :
readme2demo run <url-du-dépôt> --gemini                    # le simple drapeau lit GEMINI_MODEL

# exécution de toute la session sur OpenAI (agent OpenHands + passes OpenAI)
pip install 'readme2demo[openai]'
export OPENAI_API_KEY=sk-...
readme2demo run <url-du-dépôt> --openai gpt-5.1            # ou exportez OPENAI_MODEL une fois

# exécution de l'agent OpenHands avec un modèle Claude sur facturation API
export ANTHROPIC_API_KEY=sk-ant-...
readme2demo run <url-du-dépôt> --anthropic                 # utilise le modèle de configuration par défaut

Installation

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

Utilisation

readme2demo run https://github.com/example/tool
readme2demo run -gr https://github.com/example/tool             # identique, via le drapeau
readme2demo run -s mon_guide.md                                  # guide seul : pas de dépôt, votre guide est autonome
readme2demo run -gr https://github.com/example/tool -s mon_guide.md   # les deux : votre guide pilote tout
readme2demo run https://github.com/example/tool --gemini gemini-3.5-flash  # exécution sur Google Gemini (nécessite GEMINI_API_KEY ; utilise l'agent OpenHands ; --gemini seul lit GEMINI_MODEL)
readme2demo run https://github.com/example/tool --openai gpt-5.1           # exécution sur OpenAI (nécessite OPENAI_API_KEY ; utilise l'agent OpenHands ; --openai seul lit OPENAI_MODEL)
readme2demo run https://github.com/example/tool --anthropic                # agent OpenHands avec un modèle Claude sur ANTHROPIC_API_KEY
readme2demo run https://github.com/example/tool --allow-docker-socket  # pour les outils qui gèrent les conteneurs (COMPROMIS DE SÉCURITÉ : perce l'isolation du bac à sable — dépôts de confiance uniquement)
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-...