PR Demo Creation

Overview

Create polished terminal demos for PRs using asciinema recordings converted to GIF. The workflow: script → record → convert → embed.

Tool Selection

Goal	Tool Chain	Output
CLI demo for GitHub PR	asciinema → agg	GIF (< 5MB)
Smaller file needed	asciinema → svg-term-cli	SVG (< 500KB)
TUI screenshot	tmux → freeze	SVG/PNG

Default choice: asciinema + agg (best compatibility, GitHub renders GIFs natively)

Prerequisites

# Install tools (macOS)
brew install asciinema
cargo install --git https://github.com/asciinema/agg
npm install -g svg-term-cli  # Optional: for SVG output

Workflow

1. Script Your Demo (REQUIRED)

Before recording, write a brief script:

## Demo: [feature name]
Duration: ~20-30 seconds

1. [0-3s] Show command being typed
2. [3-10s] Command executes, show key output
3. [10-25s] Highlight the "aha moment" - what makes this valuable
4. [25-30s] Clean exit or final state

Keep it short. 20-30 seconds max. Show ONE thing well.

2. Prepare Environment

# Clean terminal state
clear
export PS1='$ '                    # Simple prompt
export TERM=xterm-256color         # Consistent colors
# Hide sensitive info (API keys, paths with usernames)

Terminal size: 100x24 (readable when scaled down)

3. Record

# Record to .cast file
asciinema rec demo.cast --cols 100 --rows 24

# Execute your scripted demo
# Press Ctrl+D or type 'exit' when done

Tips:

• Type at readable speed (not too fast)
• Pause briefly after key moments
• If you make a mistake, start over (editing is harder than re-recording)

4. Convert to GIF

# Basic conversion (recommended)
agg demo.cast demo.gif

# With speed adjustment (1.5x faster)
agg --speed 1.5 demo.cast demo.gif

# With custom font size for readability
agg --font-size 14 demo.cast demo.gif