alphacrack/readme2demoVerifizierte 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.
# readme2demo — verifizierte Tutorials & Demo-Videos aus deiner README
[](https://github.com/alphacrack/readme2demo/actions/workflows/ci.yml)
[](https://github.com/alphacrack/readme2demo/blob/main/LICENSE)
[](https://github.com/alphacrack/readme2demo/blob/main/pyproject.toml)
<!-- HERO:START — scripts/self-demo.sh rewrites this block with a fresh self-run.
Run it locally (needs Docker + VHS + a model credential):
./scripts/self-demo.sh
It runs readme2demo on this very repo, following docs/step-by-step.md,
and drops the verified demo.gif in right here. -->
[](https://github.com/alphacrack/readme2demo/tree/main/examples/readme2demo)
<sub>▶ 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 <a href="https://github.com/alphacrack/readme2demo/blob/main/examples/readme2demo">examples/readme2demo</a> · gegen ein anderes Projekt ausführen in <a href="https://github.com/alphacrack/readme2demo/blob/main/examples/toolhive">examples/toolhive</a>.</sub>
<!-- HERO:END -->
**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](https://github.com/alphacrack/readme2demo/tree/main/examples) – 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](https://github.com/alphacrack/readme2demo/blob/main/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](https://github.com/alphacrack/readme2demo/blob/main/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
```bash
# 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
```bash
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
```bash
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**:
```yaml
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](https://github.com/alphacrack/readme2demo/issues/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:
```toml
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
```bash
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](https://github.com/alphacrack/readme2demo/blob/main/SECURITY.md).
## Projekt & Community
- [Beispiele](https://github.com/alphacrack/readme2demo/tree/main/examples) – verifizierte Ausgabe als Nachweis festgeschrieben
- [Roadmap](https://github.com/alphacrack/readme2demo/blob/main/ROADMAP.md) – wohin die Reise geht (einschließlich der explorativen gehosteten/SaaS-Richtung)
- [Mitwirken](https://github.com/alphacrack/readme2demo/blob/main/CONTRIBUTING.md) – die eine nicht verhandelbare Regel und wie man sich einrichtet
- [Sicherheitsrichtlinie](https://github.com/alphacrack/readme2demo/blob/main/SECURITY.md) · [Verhaltenskodex](https://github.com/alphacrack/readme2demo/blob/main/CODE_OF_CONDUCT.md)
- [Architektur](https://github.com/alphacrack/readme2demo/blob/main/architecture/README.md) – 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!
[](https://github.com/alphacrack/readme2demo/graphs/contributors)
<a href="https://github.com/alphacrack/readme2demo/graphs/contributors">
<img src="https://contrib.rocks/image?repo=alphacrack/readme2demo" alt="Contributors" />
</a>