cli-demo-generator

CLI デモジェネレーター

プロフェッショナルなアニメーション付き CLI デモを作成します。完全自動からピクセル単位の精密な手動制御まで、4 つの方法があります。

クイックスタート

最も簡単な方法 — コマンドを指定して GIF を作成します：

python3 ${CLAUDE_SKILL_DIR}/scripts/auto_generate_demo.py \
  -c "npm install my-package" \
  -c "npm run build" \
  -o demo.gif

自動セットアップデモ — 状態を自動でクリーンアップする、繰り返し録画可能なデモ向けです：

python3 ${CLAUDE_SKILL_DIR}/scripts/auto_generate_demo.py \
  -c "npm install my-package" \
  -c "npm run build" \
  -o demo.gif \
  --bootstrap "npm uninstall my-package 2>/dev/null" \
  --speed 2

重要：VHS パーサーの制限事項

VHS の Type 文字列には $、\"、バッククォートを含められません。これらがあると解析エラーになります：

# FAILS — VHS parser rejects special chars
Type "echo \"hello $USER\""
Type "claude() { command claude \"$@\"; }"

回避策：コマンドを base64 でエンコードし、実行時にデコードします：

# 1. Encode your complex command
echo 'claude() { command claude "$@" 2>&1 | grep -v "noise"; }' | base64
# Output: Y2xhdWRlKCkgey4uLn0K

# 2. Use in tape
Type "echo Y2xhdWRlKCkgey4uLn0K | base64 -d > /tmp/wrapper.sh && source /tmp/wrapper.sh"

このパターンは、出力フィルタリング、関数定義、シェルの特殊文字を含むあらゆるコマンドで不可欠です。

方法

1. 自動生成（推奨）

python3 ${CLAUDE_SKILL_DIR}/scripts/auto_generate_demo.py \
  -c "command1" -c "command2" \
  -o output.gif \
  --title "My Demo" \
  --theme "Catppuccin Latte" \
  --font-size 24 \
  --width 1400 --height 600

フラグ	デフォルト	説明
-c	必須	含めるコマンド（繰り返し指定可能）
-o	必須	出力 GIF のパス
--title	なし	冒頭に表示するタイトル
--theme	Dracula	VHS のテーマ名
--font-size	16	フォントサイズ（pt）
--width	1400	ターミナルの幅（px）
--height	700	ターミナルの高さ（px）
--bootstrap	なし	非表示のセットアップコマンド（繰り返し指定可能）
--filter	なし	出力から除外する正規表現パターン
--speed	1	再生速度の倍率（gifsicle を使用）
--no-execute	false	.tape のみを生成

スマートタイミング：install／build／test／deploy → 3 秒、ls／pwd／echo → 1 秒、その他 → 2 秒。

2. 一括生成

1 つの設定から複数のデモを作成します：

# demos.yaml
demos:
  - name: "Install"
    output: "install.gif"
    commands: ["npm install my-package"]
  - name: "Usage"
    output: "usage.gif"
    commands: ["my-package --help", "my-package run"]

python3 ${CLAUDE_SKILL_DIR}/scripts/batch_generate.py demos.yaml --output-dir ./gifs

3. インタラクティブ録画

ライブのターミナルセッションを録画します：

bash ${CLAUDE_SKILL_DIR}/scripts/record_interactive.sh output.gif --theme "Catppuccin Latte"
# Type commands naturally, Ctrl+D when done

asciinema が必要です（brew install asciinema）。

4. 手動テープファイル

最大限に制御するには、テープを直接記述します。テンプレートは assets/templates/ にあります：

• basic.tape — シンプルなコマンドシーケンス
• interactive.tape — タイピングのシミュレーション
• self-bootstrap.tape — 非表示のセットアップを含む、自動クリーンアップ対応デモ（繰り返し使用するデモに推奨）

高度なパターン

これらのパターンは、実際の運用で使われています。詳しくは references/advanced_patterns.md を参照してください。

自動セットアップデモ

以前の状態をクリーンアップし、環境をセットアップして、それらすべてを視聴者から隠すデモです：

Hide
Type "cleanup-previous-state 2>/dev/null"
Enter
Sleep 2s
Type "clear"
Enter
Sleep 500ms
Show

Type "the-command-users-see"
Enter
Sleep 3s

Hide → コマンド → clear → Show の順序が重要です。clear はターミナルバッファーを消去し、非表示のコマンドが GIF に残るのを防ぎます。

出力ノイズのフィルタリング

冗長な出力を生成するコマンドから、不要な進捗行をフィルタリングします：

# Hidden: create a wrapper function that filters noise
Hide
Type "echo <base64-encoded-wrapper> | base64 -d > /tmp/w.sh && source /tmp/w.sh"
Enter
Sleep 500ms
Type "clear"
Enter
Sleep 500ms
Show

# Visible: clean command, filtered output
Type "my-noisy-command"
Enter
Sleep 3s

フレームの検証

録画後、主要なフレームを抽出して GIF の内容を検証します：

# Extract frames at specific positions
ffmpeg -i demo.gif -vf "select=eq(n\,100)" -frames:v 1 /tmp/frame.png -y 2>/dev/null

# View the frame (Claude can read images)
# Use Read tool on /tmp/frame.png to verify content

録画後の高速化

再録画せずに、gifsicle を使って録画を高速化します：

# 2x speed (halve frame delay)
gifsicle -d2 original.gif "#0-" > fast.gif

# 1.5x speed
gifsicle -d4 original.gif "#0-" > faster.gif

テンプレートのプレースホルダーパターン

プレースホルダーを使ってテープファイルを汎用化し、ビルド時に置換します：

# In tape file
Type "claude plugin marketplace add MARKETPLACE_REPO"

# In build script
sed "s|MARKETPLACE_REPO|$DETECTED_REPO|g" template.tape > rendered.tape
vhs rendered.tape

タイミングとサイズの参考値

用途	幅	高さ	フォント	再生時間
README／ドキュメント	1400	600	16-20	10-20 秒
プレゼンテーション	1800	900	24	15-30 秒
コンパクトな埋め込み	1200	600	14-16	10-15 秒
幅広の出力	1600	800	16	15-30 秒

詳しいガイドラインは references/best_practices.md を参照してください。

トラブルシューティング

問題	解決策
VHS がインストールされていない	brew install charmbracelet/tap/vhs
gifsicle がインストールされていない	brew install gifsicle
GIF のサイズが大きすぎる	寸法やスリープ時間を小さくするか、--speed 2 を使用します
テキストが折り返される／途切れる	--width を大きくするか、--font-size を小さくします
$ または \" で VHS の解析エラーが発生する	base64 エンコードを使用します（上記の「重要」セクションを参照）
非表示のコマンドが GIF に残る	Show の前に clear と Sleep 500ms を追加します
前のコマンドが完了する前に次のコマンドが実行される	Sleep の時間を長くします

テープファイルの構文

references/vhs_syntax.md は VHS テープファイルの完全なリファレンスです。すべてのコマンド、設定、キー名と、それぞれが受け付ける引数の形式を記載しています。手動でテープを作成するとき、テープの解析には成功するものの動作が予想と異なるとき、またはこの SKILL.md に例のないコマンドが必要なときに参照してください。

Dependencies

Required: VHS (brew install charmbracelet/tap/vhs)

Optional: gifsicle (speed-up), asciinema (interactive recording), ffmpeg (frame verification), PyYAML (batch YAML configs)