readme2demo — verifizierte Tutorials & Demo-Videos aus deiner README

_{▶ 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 () oder exportiere einmal. Installiere das 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

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:

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.
Das Repository bringt eine mit (step_by_step.md / step-by-step.md im Stammverzeichnis oder docs/, beliebige Groß-/Kleinschreibung): gleiche Behandlung, automatisch.
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

Beispiele – verifizierte Ausgabe als Nachweis festgeschrieben
Roadmap – wohin die Reise geht (einschließlich der explorativen gehosteten/SaaS-Richtung)
Mitwirken – die eine nicht verhandelbare Regel und wie man sich einrichtet
Sicherheitsrichtlinie · Verhaltenskodex
Architektur – Stufengrenzen und Diagramme

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!

readme2demo

Beliebteste