Zurück zu den Updates
New releaseAug 8, 2026

readme2demo v0.8.0

Verifizierte Tutorials und Demovideos aus Ihrer README. Ein KI-Agent führt sie in einer gehärteten Docker-Sandbox aus und spielt sie in einem frischen Container ab, bevor etwas veröffentlicht wird.

Teilen

readme2demo — verifizierte Tutorials & Demo-Videos aus deiner README

tests License: MIT Python 3.10+

readme2demo, das auf seinem eigenen Repository läuft — verifiziertes Demo

▶ readme2demo erstellt sein eigenes Tutorial: Ein KI-Agent führt das README dieses Repositorys in einer Sandbox aus, ein frischer Container wiederholt jeden Schritt, dann wird das Demo gerendert. Vollständige Selbstausführungsausgabe in examples/readme2demo · gegen ein anderes Projekt ausführen in examples/toolhive.

KI-verifizierter Tutorial- und Demo-Video-Generator. Gib ein Repository an. Ein KI-Agent liest das README und führt es tatsächlich in einer gehärteten Docker-Sandbox aus. Nur wenn ein Clean-Room-Replay erfolgreich ist, rendert er ein Demo-Video (VHS) und veröffentlicht das Tutorial, die Schritt-für-Schritt-Anleitung und das Troubleshooting-Dokument.

Der Wert liegt nicht darin, dass „KI ein Tutorial schreibt“ – sondern darin, dass das Tutorial zweimal ausgeführt wurde, bevor du es gesehen hast.

In Aktion sehen: Durchstöbere verifizierte Beispielausführungen – echte Tutorials, Schritt-für-Schritt-Anleitungen und Demo-Videos, jede unabhängig in einem sauberen Container wiederholt, bevor sie veröffentlicht wurden.

So funktioniert es

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

Siehe architecture/README.md für die vollständige Architektur.

Anforderungen

  • Python ≥ 3.10, Docker
  • Authentifizierung, eine von:
    • Dein Claude-Abonnement (kein API-Key): Eine lokale Claude Code-Installation. Die Planner/Distiller/Tutorial-Durchläufe laufen über dein Abonnement mit --llm-backend claude-cli (claude -p), und der Agent in der Sandbox authentifiziert sich mit CLAUDE_CODE_OAUTH_TOKEN (erstellen mit: claude setup-token). Vollständig unterstützt für selbstgehostete Einzelbetreiber-Ausführungen gegen eigene Repositories – Pro/Max-Pläne enthalten ein monatliches Agent-SDK-Guthaben, das claude -p abdeckt.
    • ANTHROPIC_API_KEY – API-Abrechnung nach Verbrauch; am besten für Skalierung und Parallelität, und erforderlich, wenn du readme2demo als Dienst für andere hostest (gemäß den Anthropic-Bedingungen darf die Abonnement-Authentifizierung möglicherweise kein Multi-Tenant-Produkt betreiben – siehe ROADMAP.md). Füge --anthropic [model] hinzu, um den Sandbox-Agenten auf der OpenHands-Engine mit einem Claude-Modell anstelle von claude-code auszuführen.
    • Google Gemini (--gemini [model]): Ein einzelner GEMINI_API_KEY betreibt die gesamte Sitzung ohne Claude – die Planner/Distiller/Tutorial-Durchläufe verwenden Gemini und der Sandbox-Agent läuft auf der OpenHands-Engine (ebenfalls auf Gemini). Kein Modellname ist fest verdrahtet (Google stellt alte Modelle mit einem harten 404 ein): Benenne es pro Ausführung (--gemini gemini-3.5-flash) oder exportiere GEMINI_MODEL einmal. Installiere das Extra: pip install 'readme2demo[gemini]'.
    • OpenAI (--openai [model]): Gleiche Form wie Gemini – ein einzelner OPENAI_API_KEY betreibt die Durchläufe und den OpenHands-Agenten, kein Modellname ist fest verdrahtet (--openai gpt-5.1 oder exportiere OPENAI_MODEL). Installiere das Extra: pip install 'readme2demo[openai]'.
  • Optional: LLM_API_KEY + LLM_MODEL für --engine openhands (experimentell) mit einem anderen litellm-Anbieter – die obigen Voreinstellungen füllen sie automatisch aus
# 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

Installieren

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

Verwendung

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

Das Repository ist optional: übergib es positional oder mit -gr/--github-repo, gib eine Anleitung mit -s/--step-by-step an, oder beides. Mindestens eines ist erforderlich. Mit einer Anleitung allein wird kein Repository geklont – die Anleitung muss in sich geschlossen sein (ein veröffentlichtes Paket installieren oder klonen, was sie benötigt, als expliziten Schritt); das Fresh-Container-Replay überprüft trotzdem jeden Befehl.

Ausgaben landen in runs/<run-id>/: tutorial.md, step_by_step.md, troubleshooting.md, commands.sh, demo.tape, demo.mp4, demo.gif, plus manifest.json mit Stadium-Status und Gesamtkosten.

GitHub Action – überprüfe deine README in CI

Erhalte ein rotes X, wenn deine README nicht mehr funktioniert. Die Composite-Action im Repository-Root installiert readme2demo aus ihrem eigenen gepinnten Checkout, baut das Sandbox-Image, führt die gesamte Pipeline gegen die URL deines Repositorys aus und lässt den Check fehlschlagen, wenn das Fresh-Container-Replay nicht besteht:

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"

⚠ Nur URL-Modus – dies überprüft noch keine PR-Heads. Die Action klont den Remote-Standard-Branch-HEAD von repo-url (Standard: das Repository, das den Workflow ausführt); die Aufnahme akzeptiert nur HTTPS-URLs, --depth 1, kein Ref-Pinning. Bei pull_request würde sie die README des Basis-Branches testen – nicht die des PRs – also verknüpfe sie nicht mit PRs, die ein Pre-Merge-Urteil erwarten. Bis #74 (Lokaler-Pfad-Aufnahme) eintrifft, sind on: push auf den Standard-Branch und ein Cron die ehrlichen Auslöser; eine repo-path-Eingabe für echte PR-Head-Überprüfung kommt damit.

Kosten: Jede Ausführung gibt echtes Agentengeld auf deinem ANTHROPIC_API_KEY aus – typischerweise ein paar Dollar, hart gedeckelt durch budget-usd (Standard "5"; die Ausführung wird abgebrochen, wenn überschritten). Der paths:-Filter plus ein Cron hält die Ausgaben im Verhältnis zum README-Wechsel, und skip-video: "true" verkürzt die Wandzeit (das Rendern kostet auch kein API-Geld, egal wie).

Der Check schlägt auf zwei unterscheidbare Arten fehl, benannt im Schritt-Log: README kaputt (Pipeline abgeschlossen, Clean-Room-Replay fehlgeschlagen – erkannt über readme2demo report --json, weil readme2demo run absichtlich mit Exit 0 bei einer abgeschlossenen, aber nicht verifizierten Ausführung beendet wird) und Action-Infrastruktur kaputt (Pipeline-Exit ungleich Null: Preflight, Budget, Docker). Ausgaben: verified ("true"/"false") und run-dir; tutorial.md, step_by_step.md, verify.log (und demo.gif wenn Video an) werden als das readme2demo-run-Artefakt hochgeladen.

step_by_step.md – die Quelle des Videos

Das Demo-Video wird immer aus step_by_step.md erstellt: seine Schritte werden geparst, und jeder demo-sichere, fundierte Befehl wird zu einem getippten Befehl im Video, wobei der Schritt-Titel als On-Screen-Kommentar angezeigt wird. Drei Wege, wie es entsteht, in Prioritätsreihenfolge:

  1. Du übergibst eine: readme2demo run <url> -s my_guide.md – wird in den Klon als maßgebliche Anleitung injiziert; Planner und Agent folgen ihr, das Video spielt sie ab. Das <url> ist hier optional: readme2demo run -s my_guide.md führt nur mit Anleitung gegen eine leere Sandbox aus.
  2. Das Repository bringt eine mit (step_by_step.md / step-by-step.md im Stammverzeichnis oder docs/, beliebige Groß-/Kleinschreibung): gleiche Behandlung, automatisch.
  3. Keine vorhanden: Die Pipeline generiert eine detaillierte step_by_step.md – jeden Befehl aus dem verifizierten commands.sh als nummerierten Schritt mit echten erfassten Ausgaben – und erstellt dann das Video daraus. Bereit, wieder in das Repository eingebracht zu werden.

Setup-Schritte (Klonen, Installieren, Bauen) werden in der Anleitung dokumentiert, aber aus dem Video herausgehalten – es spielt gegen den verifizierten, bereits erstellten Arbeitsbaum und zeigt den Nutzen.

Jedes Tutorial trägt ein Verifikationsabzeichen: ✅ Verified on <Datum> · image <Digest> · commit <SHA> – oder ein lautes ⚠ UNVERIFIED, wenn das Replay nicht bestanden wurde. Unverifizierte Ausgabe wird nie stillschweigend veröffentlicht.

Konfiguration

CLI-Flags > readme2demo.toml > Standardwerte:

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

Entwicklung

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)

Sicherheitsmodell

READMEs sind nicht vertrauenswürdiger Code. Der Agent läuft innerhalb eines gehärteten Containers (cap-drop ALL, no-new-privileges, memory/cpu/pids limits, non-root) – dieser Container ist die Berechtigungsgrenze. Bekannter MVP-Kompromiss: Der API-Key gelangt in die Sandbox; verwende einen dedizierten, niedrig limitierten Key. Ein hostseitiger Schlüssel-injizierender Egress-Proxy ist geplant (Meilenstein 4).

Vollständiges Bedrohungsmodell und private Schwachstellenmeldung: SECURITY.md.

Projekt & Community

MIT lizenziert. Die CLI und der Verifizierungsprozess sind und bleiben kostenlos und Open Source.

Mitwirkende

Ein großes Dankeschön an alle, die zu readme2demo beigetragen haben!

Contributors

Contributors
Mehr lesen

Kategorien

Dynamische Analyse (Sandboxing)Scripting & AutomatisierungDevSecOpsDienstprogramme & FrameworksLernen & Bildung