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.

Os resultados vão para runs/<run-id>/: tutorial.md, step_by_step.md, troubleshooting.md, commands.sh, demo.tape, demo.mp4, demo.gif, além de manifest.json com status dos estágios e custo total.

GitHub Action — verifique seu README no CI

Obtenha um X vermelho quando seu README parar de funcionar. A ação composta na raiz do repositório instala readme2demo a partir de seu próprio checkout fixo, constrói a imagem da sandbox, executa o pipeline completo contra a URL do seu repositório e falha na verificação quando a repetição em contêiner limpo não passa:

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"

⚠ Apenas modo URL — isso ainda NÃO verifica heads de PR. A ação clona o HEAD do branch padrão remoto de repo-url (padrão: o repositório executando o workflow); a ingestão aceita apenas URLs https, --depth 1, sem fixação de ref. Em pull_request, testaria o README do branch base — não o do PR — portanto, não o conecte a PRs esperando um veredito pré-merge. Até que #74 (ingestão por caminho local) chegue, on: push no branch padrão e um cron são os gatilhos honestos; uma entrada repo-path para verificação real de head de PR chegará com ele.

Custo: cada execução gasta dinheiro real do agente em sua ANTHROPIC_API_KEY — normalmente alguns dólares, com limite máximo definido por budget-usd (padrão "5"; a execução é abortada se excedido). O filtro paths: mais um cron mantém o gasto proporcional à rotatividade do README, e skip-video: "true" reduz o tempo de parede (a renderização não custa dinheiro de API de qualquer maneira).

A verificação falha de duas formas distinguíveis, nomeadas no log da etapa: README quebrado (pipeline concluído, repetição em ambiente limpo falhou — detectado via readme2demo report --json, porque readme2demo run deliberadamente sai com 0 em uma execução concluída mas não verificada) e infra da ação quebrada (saída de pipeline não zero: pré-voo, orçamento, Docker). Saídas: verified ("true"/"false") e run-dir; tutorial.md, step_by_step.md, verify.log (e demo.gif quando o vídeo está ligado) são enviados como o artefato readme2demo-run.

step_by_step.md — a fonte do vídeo

O vídeo de demonstração é sempre construído a partir do step_by_step.md: seus passos são analisados, e todo comando seguro para demonstração e fundamentado se torna um comando digitado no vídeo com o título do passo mostrado como um comentário na tela. Três maneiras de ele existir, em ordem de prioridade:

1. Você passa um: readme2demo run <url> -s my_guide.md — injetado no clone como o guia autoritativo; planejador e agente o seguem, o vídeo o reproduz. O <url> é opcional aqui: readme2demo run -s my_guide.md executa apenas o guia contra uma sandbox vazia.
2. O repositório fornece um (step_by_step.md / step-by-step.md na raiz ou em docs/, qualquer capitalização): mesmo tratamento, automaticamente.
3. Nenhum existe: o pipeline gera um step_by_step.md detalhado — cada comando do commands.sh verificado como um passo numerado com saídas reais capturadas — e então constrói o vídeo a partir dele. Pronto para ser contribuído de volta ao repositório.

Passos de configuração (clones, instalações, builds) são documentados no guia, mas mantidos fora do vídeo — ele é reproduzido contra a árvore de trabalho já verificada e construída, mostrando o resultado final.

Cada tutorial carrega um selo de verificação: ✅ Verificado em <data> · imagem <digest> · commit <sha> — ou um alto ⚠ NÃO VERIFICADO se a repetição não passou. Saída não verificada nunca é publicada silenciosamente.

Configuração

Flags CLI > readme2demo.toml > padrões:

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

Desenvolvimento

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)

Modelo de segurança

READMEs são código não confiável. O agente executa dentro de um contêiner reforçado (cap-drop ALL, no-new-privileges, limites de memória/cpu/pids, não-root) — esse contêiner é o limite de permissão. Compensação conhecida do MVP: a chave da API entra na sandbox; use uma chave dedicada de baixo limite. Um proxy de egresso injetor de chave no lado do host está planejado (Marco 4).

Modelo de ameaça completo e relatório de vulnerabilidade privada: SECURITY.md.

Projeto e comunidade

• Exemplos — saída verificada comprometida como prova
• Roadmap — para onde isso está indo (incluindo a direção exploratória hospedada/SaaS)
• Contribuindo — a única regra inegociável e como se preparar
• Política de segurança · Código de Conduta
• Arquitetura — limites de estágio e diagramas

Licenciado sob MIT. A CLI e o pipeline de verificação são, e continuarão sendo, gratuitos e de código aberto.

Contribuidores

Um enorme agradecimento a todos que contribuíram para o readme2demo!