alphacrack/readme2demoTutoriais verificados e vídeos de demonstração do seu README. Um agente de IA executa isso em um sandbox Docker reforçado e o reproduz em um contêiner novo antes de qualquer coisa ser publicada.
# readme2demo — tutoriais verificados e vídeos de demonstração a partir do seu 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 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 <a href="https://github.com/alphacrack/readme2demo/blob/main/examples/readme2demo">examples/readme2demo</a> · execute contra outro projeto em <a href="https://github.com/alphacrack/readme2demo/blob/main/examples/toolhive">examples/toolhive</a>.</sub>
<!-- HERO:END -->
**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](https://github.com/alphacrack/readme2demo/tree/main/examples) — 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](https://github.com/alphacrack/readme2demo/blob/main/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](https://github.com/alphacrack/readme2demo/blob/main/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
```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
```
## Instalação
```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
```
## Uso
```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-...
```
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**:
```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"
```
> **⚠ 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](https://github.com/alphacrack/readme2demo/issues/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:
```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
```
## Desenvolvimento
```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)
```
## 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](https://github.com/alphacrack/readme2demo/blob/main/SECURITY.md).
## Projeto e comunidade
- [Exemplos](https://github.com/alphacrack/readme2demo/tree/main/examples) — saída verificada comprometida como prova
- [Roadmap](https://github.com/alphacrack/readme2demo/blob/main/ROADMAP.md) — para onde isso está indo (incluindo a direção exploratória hospedada/SaaS)
- [Contribuindo](https://github.com/alphacrack/readme2demo/blob/main/CONTRIBUTING.md) — a única regra inegociável e como se preparar
- [Política de segurança](https://github.com/alphacrack/readme2demo/blob/main/SECURITY.md) · [Código de Conduta](https://github.com/alphacrack/readme2demo/blob/main/CODE_OF_CONDUCT.md)
- [Arquitetura](https://github.com/alphacrack/readme2demo/blob/main/architecture/README.md) — 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!
[](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="Contribuidores" />
</a>