readme2demo — tutoriais verificados e vídeos de demonstração a partir do seu README

_{▶ readme2demo gerando seu próprio tutorial: um agente de IA executa o README deste repositório em uma sandbox, um novo contêiner repete cada passo, e então a demonstração é renderizada. Saída completa da auto-execução em examples/readme2demo · execute contra outro projeto em examples/toolhive.}

Gerador de tutoriais e vídeos de demonstração verificados por IA. Aponte para um repositório. Um agente de IA lê o README e realmente o executa dentro de uma sandbox Docker reforçada. Somente após uma repetição em ambiente limpo passar, ele renderiza um vídeo de demonstração (VHS) e publica o tutorial, o guia passo a passo e o documento de solução de problemas.

O valor não é "IA escreve um tutorial" — é que o tutorial executou, duas vezes, antes que você o visse.

Veja em ação: navegue por execuções de exemplo verificadas — tutoriais reais, guias passo a passo e vídeos de demonstração, cada um reproduzido de forma independente em um contêiner limpo antes da publicação.

Como funciona

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

Veja architecture/README.md para a arquitetura completa.

Requisitos

Python ≥ 3.10, Docker
Autenticação, uma de:
- Sua assinatura Claude (sem chave de API): uma instalação local do Claude Code. As passagens do planejador/destilador/tutorial são executadas em sua assinatura via --llm-backend claude-cli (claude -p), e o agente dentro da sandbox autentica com CLAUDE_CODE_OAUTH_TOKEN (crie um: claude setup-token). Totalmente suportado para execuções auto-hospedadas e operador único contra seus próprios repositórios — os planos Pro/Max incluem um crédito mensal do Agent SDK que cobre claude -p.
- ANTHROPIC_API_KEY — faturamento de API por consumo; melhor para escala e concorrência, e obrigatório se você hospedar readme2demo como um serviço para outros (de acordo com os termos da Anthropic, a autenticação por assinatura pode não alimentar um produto multi-inquilino — veja ROADMAP.md). Adicione --anthropic [model] para executar o agente em sandbox no motor OpenHands com um modelo Claude em vez de claude-code.
- Google Gemini (--gemini [model]): uma única GEMINI_API_KEY executa toda a sessão fora do Claude — as passagens do planejador/destilador/tutorial usam Gemini e o agente em sandbox é executado no motor OpenHands (também no Gemini). Nenhum nome de modelo está embutido (o Google retira modelos antigos com um 404 fixo): nomeie por execução (--gemini gemini-3.5-flash) ou exporte GEMINI_MODEL uma vez. Instale o extra: pip install 'readme2demo[gemini]'.
- OpenAI (--openai [model]): mesma forma que o Gemini — uma única OPENAI_API_KEY alimenta as passagens e o agente OpenHands, nenhum nome de modelo está embutido (--openai gpt-5.1 ou exporte OPENAI_MODEL). Instale o extra: pip install 'readme2demo[openai]'.
Opcional: LLM_API_KEY + LLM_MODEL para --engine openhands (experimental) com qualquer outro provedor litellm — as predefinições acima os preenchem automaticamente

# 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

Instalação

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

Uso

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

O repositório é opcional: passe-o posicionalmente ou com -gr/--github-repo, forneça um guia com -s/--step-by-step, ou ambos. Pelo menos um é necessário. Com apenas um guia, nenhum repositório é clonado — o guia deve ser autocontido (instalar um pacote publicado ou clonar o que precisa como um passo explícito); a repetição em contêiner limpo ainda verifica cada comando.

readme2demo v0.7.5