readme2demo v0.7.5
Verified tutorials and demo videos from your README. An AI agent runs it in a hardened Docker sandbox and replays it in a fresh container before anything is published.
readme2demo — verified tutorials & demo videos from your README
▶ readme2demo generating its own tutorial: an AI agent runs this repo's README in a sandbox, a fresh container replays every step, then the demo is rendered. Full self-run output in examples/readme2demo · run against another project in examples/toolhive.
AI-verified tutorial and demo video generator. Point it at a repo. An AI agent reads the README and actually runs it inside a hardened Docker sandbox. Only after a clean-room replay passes does it render a demo video (VHS) and publish the tutorial, step-by-step guide, and troubleshooting doc.
The value is not "AI writes a tutorial" — it's that the tutorial ran, twice, before you saw it.
See it in action: browse verified example runs — real tutorials, step-by-step guides, and demo videos, each independently replayed in a clean container before publishing.
How it works
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
See architecture/README.md for the full architecture.
Requirements
- Python ≥ 3.10, Docker
- Auth, one of:
- Your Claude subscription (no API key): a local Claude Code install. The planner/distiller/tutorial passes run on your subscription via
--llm-backend claude-cli(claude -p), and the in-sandbox agent authenticates withCLAUDE_CODE_OAUTH_TOKEN(create one:claude setup-token). Fully supported for self-hosted, single-operator runs against your own repos — Pro/Max plans include a monthly Agent SDK credit that coversclaude -p. ANTHROPIC_API_KEY— metered API billing; best for scale and concurrency, and required if you host readme2demo as a service for others (per Anthropic's terms, subscription auth may not power a multi-tenant product — see ROADMAP.md). Add--anthropic [model]to run the sandboxed agent on the OpenHands engine with a Claude model instead of claude-code.- Google Gemini (
--gemini [model]): a singleGEMINI_API_KEYruns the whole session off Claude — the planner/distiller/tutorial passes use Gemini and the sandboxed agent runs on the OpenHands engine (also on Gemini). No model name is built in (Google retires old ones with a hard 404): name it per run (--gemini gemini-3.5-flash) or exportGEMINI_MODELonce. Install the extra:pip install 'readme2demo[gemini]'. - OpenAI (
--openai [model]): same shape as Gemini — a singleOPENAI_API_KEYpowers the passes and the OpenHands agent, no model name is built in (--openai gpt-5.1or exportOPENAI_MODEL). Install the extra:pip install 'readme2demo[openai]'.
- Your Claude subscription (no API key): a local Claude Code install. The planner/distiller/tutorial passes run on your subscription via
- Optional:
LLM_API_KEY+LLM_MODELfor--engine openhands(experimental) with any other litellm provider — the presets above fill them automatically
# 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
Install
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
Usage
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-...
The repo is optional: pass it positionally or with -gr/--github-repo, supply a guide with -s/--step-by-step, or both. At least one is required. With a guide alone, no repo is cloned — the guide must be self-contained (install a published package, or clone what it needs as an explicit step); the fresh-container replay still verifies every command.
Outputs land in runs/<run-id>/: tutorial.md, step_by_step.md, troubleshooting.md, commands.sh, demo.tape, demo.mp4, demo.gif, plus manifest.json with stage statuses and total cost.