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）、を一度エクスポートしてください。追加インストール: 。

# 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入力が追加されます。

コスト: 実行ごとに実際のエージェント費用がANTHROPIC_API_KEYに発生します — 通常は数ドルで、budget-usd（デフォルト"5"、超過すると実行が中断されます）によってハードキャップされます。paths:フィルターとcronにより、費用はREADMEの変更頻度に比例し、skip-video: "true"でウォールクロック時間を短縮します（レンダリングにはどちらにせよAPI費用はかかりません）。

チェックは2つの区別可能な方法で失敗します。ステップログに名前が表示されます: README broken（パイプライン完了、クリーンルームリプレイ失敗 — readme2demo report --jsonで検出。readme2demo runは完了したが未検証の実行でも意図的に終了コード0を返すため）およびaction infra broke（ゼロ以外のパイプライン終了: 事前チェック、予算、Docker）。出力: verified（"true"/"false"）およびrun-dir。tutorial.md、step_by_step.md、verify.log（ビデオオンの場合はdemo.gif）がreadme2demo-runアーティファクトとしてアップロードされます。

step_by_step.md — 動画のソース

デモ動画は常にstep_by_step.mdから構築されます: そのステップが解析され、デモセーフで根拠のあるすべてのコマンドが動画内で入力されるコマンドになり、ステップタイトルが画面上のコメントとして表示されます。優先順位付きで3つの方法で存在します:

自分で渡す: readme2demo run <url> -s my_guide.md — クローン内に権威あるガイドとして注入され、プランナーとエージェントがそれに従い、動画がそれを再生します。ここで<url>はオプションです: readme2demo run -s my_guide.mdは空のサンドボックスに対してガイドのみを実行します。
リポジトリが提供する（step_by_step.md / step-by-step.md ルートまたはdocs/、大文字小文字任意）: 同じ処理、自動的に。
どちらも存在しない: パイプラインが詳細なstep_by_step.mdを生成します — 検証済みcommands.shのすべてのコマンドを、実際のキャプチャ出力付きの番号付きステップとして — その後、そこから動画を構築します。リポジトリにコントリビュートする準備ができています。

セットアップ手順（クローン、インストール、ビルド）はガイドに文書化されますが、動画からは除外されます — 動画は検証済みで既にビルドされたワークツリーに対して再生され、結果を示します。

すべてのチュートリアルには検証バッジが付いています: ✅ Verified on <date> · image <digest> · commit <sha> — リプレイが成功しなかった場合は大きな⚠ UNVERIFIED。未検証の出力が静かに公開されることはありません。

設定

CLIフラグ > readme2demo.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

開発

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)

セキュリティモデル

READMEは信頼できないコードです。エージェントは強化されたコンテナ（cap-drop ALL、no-new-privileges、メモリ/CPU/プロセス制限、非root）内部で実行されます — そのコンテナが権限境界です。既知のMVPトレードオフ: APIキーがサンドボックスに入ります。専用の低制限キーを使用してください。ホスト側のキーインジェクションイーグレスプロキシが計画されています（マイルストーン4）。

完全な脅威モデルと非公開脆弱性報告: SECURITY.md。

プロジェクトとコミュニティ

Examples — 検証済み出力が証拠としてコミットされています
Roadmap — 今後の方向性（探索的なホスト型/SaaS方向も含む）
Contributing — 唯一の不可侵ルールとセットアップ方法
Security policy · Code of Conduct
Architecture — ステージ境界と図

MITライセンス。CLIと検証パイプラインは、今後も無料でオープンソースであり続けます。

コントリビューター

readme2demoに貢献してくださったすべての方々に心から感謝します！

readme2demo

人気