alphacrack/readme2demoREADMEから検証済みのチュートリアルとデモ動画。AIエージェントは堅牢なDockerサンドボックスでそれを実行し、公開前に新しいコンテナで再生します。
# readme2demo — 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が自身のチュートリアルを生成: AIエージェントがこのリポジトリのREADMEをサンドボックス内で実行し、新しいコンテナがすべての手順をリプレイし、デモがレンダリングされます。完全な自己実行出力は<a href="https://github.com/alphacrack/readme2demo/blob/main/examples/readme2demo">examples/readme2demo</a>にあります。別のプロジェクトでの実行例は<a href="https://github.com/alphacrack/readme2demo/blob/main/examples/toolhive">examples/toolhive</a>。</sub>
<!-- HERO:END -->
**AI検証済みチュートリアル＆デモ動画ジェネレーター。** リポジトリを指定すると、AIエージェントがREADMEを読み取り、実際に強化されたDockerサンドボックス内で実行します。クリーンルームリプレイが成功した後にのみ、デモ動画（VHS）をレンダリングし、チュートリアル、ステップバイステップガイド、トラブルシューティングドキュメントを公開します。
価値は「AIがチュートリアルを書く」ことではなく、チュートリアルがあなたの目に触れる前に**2回実行された**ことです。
**実際の動作を見る:** [検証済み実行例](https://github.com/alphacrack/readme2demo/tree/main/examples)を参照 — 実際のチュートリアル、ステップバイステップガイド、デモ動画が、それぞれ独立してクリーンコンテナでリプレイされた後に公開されています。
## 仕組み
```
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](https://github.com/alphacrack/readme2demo/blob/main/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](https://github.com/alphacrack/readme2demo/blob/main/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` — 上記のプリセットはこれらを自動的に設定します
```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
```
## インストール
```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
```
## 使用法
```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-...
```
リポジトリは**オプション**: 位置引数または`-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に対してパイプライン全体を実行し、**新しいコンテナのリプレイが成功しなかった場合にチェックを失敗させます**:
```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"
```
> **⚠ URLモードのみ — これはPR HEADをまだ検証しません。** アクションは`repo-url`（デフォルト: ワークフローを実行しているリポジトリ）の**リモートデフォルトブランチHEAD**をクローンします。インジェストはhttps URLのみを受け付け、`--depth 1`、リファレンス固定なしです。`pull_request`では、PRではなく*ベース*ブランチのREADMEをテストするため、マージ前の判定を期待してPRに配線しないでください。[#74](https://github.com/alphacrack/readme2demo/issues/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つの方法で存在します:
1. **自分で渡す**: `readme2demo run <url> -s my_guide.md` — クローン内に権威あるガイドとして注入され、プランナーとエージェントがそれに従い、動画がそれを再生します。ここで`<url>`はオプションです: `readme2demo run -s my_guide.md`は空のサンドボックスに対してガイドのみを実行します。
2. **リポジトリが提供する**（`step_by_step.md` / `step-by-step.md` ルートまたは`docs/`、大文字小文字任意）: 同じ処理、自動的に。
3. **どちらも存在しない**: パイプラインが詳細な`step_by_step.md`を*生成*します — 検証済み`commands.sh`のすべてのコマンドを、実際のキャプチャ出力付きの番号付きステップとして — その後、そこから動画を構築します。リポジトリにコントリビュートする準備ができています。
セットアップ手順（クローン、インストール、ビルド）はガイドに文書化されますが、動画からは除外されます — 動画は検証済みで既にビルドされたワークツリーに対して再生され、結果を示します。
すべてのチュートリアルには検証バッジが付いています: `✅ Verified on <date> · image <digest> · commit <sha>` — リプレイが成功しなかった場合は大きな`⚠ UNVERIFIED`。未検証の出力が静かに公開されることはありません。
## 設定
CLIフラグ > `readme2demo.toml` > デフォルト:
```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
```
## 開発
```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)
```
## セキュリティモデル
READMEは信頼できないコードです。エージェントは強化されたコンテナ（cap-drop ALL、no-new-privileges、メモリ/CPU/プロセス制限、非root）*内部*で実行されます — そのコンテナが権限境界です。既知のMVPトレードオフ: APIキーがサンドボックスに入ります。専用の低制限キーを使用してください。ホスト側のキーインジェクションイーグレスプロキシが計画されています（マイルストーン4）。
完全な脅威モデルと非公開脆弱性報告: [SECURITY.md](https://github.com/alphacrack/readme2demo/blob/main/SECURITY.md)。
## プロジェクトとコミュニティ
- [Examples](https://github.com/alphacrack/readme2demo/tree/main/examples) — 検証済み出力が証拠としてコミットされています
- [Roadmap](https://github.com/alphacrack/readme2demo/blob/main/ROADMAP.md) — 今後の方向性（探索的なホスト型/SaaS方向も含む）
- [Contributing](https://github.com/alphacrack/readme2demo/blob/main/CONTRIBUTING.md) — 唯一の不可侵ルールとセットアップ方法
- [Security policy](https://github.com/alphacrack/readme2demo/blob/main/SECURITY.md) · [Code of Conduct](https://github.com/alphacrack/readme2demo/blob/main/CODE_OF_CONDUCT.md)
- [Architecture](https://github.com/alphacrack/readme2demo/blob/main/architecture/README.md) — ステージ境界と図
MITライセンス。CLIと検証パイプラインは、今後も無料でオープンソースであり続けます。
## コントリビューター
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="Contributors" />
</a>