readme2demo — READMEから検証済みチュートリアル＆デモ動画

_{▶ readme2demoが自身のチュートリアルを生成: AIエージェントがこのリポジトリのREADMEをサンドボックス内で実行し、新しいコンテナがすべての手順をリプレイし、デモがレンダリングされます。完全な自己実行出力はexamples/readme2demoにあります。別のプロジェクトでの実行例はexamples/toolhive。}

AI検証済みチュートリアル＆デモ動画ジェネレーター。 リポジトリを指定すると、AIエージェントがREADMEを読み取り、実際に強化されたDockerサンドボックス内で実行します。クリーンルームリプレイが成功した後にのみ、デモ動画（VHS）をレンダリングし、チュートリアル、ステップバイステップガイド、トラブルシューティングドキュメントを公開します。

価値は「AIがチュートリアルを書く」ことではなく、チュートリアルがあなたの目に触れる前に2回実行されたことです。

実際の動作を見る: 検証済み実行例を参照 — 実際のチュートリアル、ステップバイステップガイド、デモ動画が、それぞれ独立してクリーンコンテナでリプレイされた後に公開されています。

仕組み

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

完全なアーキテクチャについてはarchitecture/README.mdを参照してください。

必要条件

Python ≥ 3.10, Docker
認証 (以下のいずれか):
- Claudeサブスクリプション (APIキー不要): ローカルのClaude Codeインストール。プランナー/ディスティラー/チュートリアルパスは--llm-backend claude-cli (claude -p) 経由でサブスクリプション上で実行され、サンドボックス内のエージェントはCLAUDE_CODE_OAUTH_TOKENで認証します（作成方法: claude setup-token）。セルフホステッド、単一オペレーターの自身のリポジトリに対する実行で完全サポート — Pro/Maxプランにはclaude -pをカバーする月間Agent SDKクレジットが含まれています。
- ANTHROPIC_API_KEY — 従量課金API; スケールと同時実行性に最適で、readme2demoを他者のためのサービスとしてホストする場合に必要（Anthropicの利用規約により、サブスクリプション認証はマルチテナント製品には使用できない場合があります — ROADMAP.md参照）。--anthropic [model]を追加すると、サンドボックスエージェントがclaude-codeの代わりにClaudeモデルでOpenHandsエンジン上で実行されます。
- Google Gemini (--gemini [model]): 単一のGEMINI_API_KEYでセッション全体がClaudeから切り替わります — プランナー/ディスティラー/チュートリアルパスはGeminiを使用し、サンドボックスエージェントはOpenHandsエンジン（Gemini搭載）で実行されます。モデル名は組み込まれていません（Googleは古いモデルをハード404で廃止します）: 実行ごとに命名するか（--gemini gemini-3.5-flash）、GEMINI_MODELを一度エクスポートしてください。追加インストール: pip install 'readme2demo[gemini]'。
- OpenAI (--openai [model]): Geminiと同じ形状 — 単一のOPENAI_API_KEYでパスとOpenHandsエージェントを動作させ、モデル名は組み込まれていません（--openai gpt-5.1またはOPENAI_MODELをエクスポート）。追加インストール: pip install 'readme2demo[openai]'。
オプション: その他のlitellmプロバイダーで--engine openhands（実験的）を使用するためのLLM_API_KEY + LLM_MODEL — 上記のプリセットはこれらを自動的に設定します

# 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

インストール

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

使用法

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

リポジトリはオプション: 位置引数または-gr/--github-repoで指定するか、-s/--step-by-stepでガイドを指定するか、両方を指定します。少なくとも1つが必要です。ガイドのみの場合、リポジトリはクローンされません — ガイドは自己完結型である必要があります（公開パッケージをインストールするか、明示的なステップとして必要なものをクローンする）。新しいコンテナのリプレイはすべてのコマンドを検証します。

出力はruns/<run-id>/に格納されます: tutorial.md, step_by_step.md, troubleshooting.md, commands.sh, demo.tape, demo.mp4, demo.gif、さらにステージステータスと総コストを含むmanifest.json。

GitHub Action — CIでREADMEを検証

READMEが動かなくなったときに赤いXを取得します。リポジトリルートの複合アクションは、自身の固定チェックアウトからreadme2demoをインストールし、サンドボックスイメージをビルドし、リポジトリのURLに対してパイプライン全体を実行し、新しいコンテナのリプレイが成功しなかった場合にチェックを失敗させます:

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"

⚠ URLモードのみ — これはPR HEADをまだ検証しません。 アクションはrepo-url（デフォルト: ワークフローを実行しているリポジトリ）のリモートデフォルトブランチHEADをクローンします。インジェストはhttps URLのみを受け付け、--depth 1、リファレンス固定なしです。pull_requestでは、PRではなくベースブランチのREADMEをテストするため、マージ前の判定を期待してPRに配線しないでください。#74（ローカルパスインジェスト）が導入されるまで、デフォルトブランチへのon: pushとcronが正直なトリガーです。それに伴い、実際のPR HEAD検証のためのrepo-path入力が追加されます。

readme2demo v0.7.5