| name | pr-demo |
| description | Use when creating animated demos (GIFs) for pull requests or documentation. Covers terminal recording with asciinema and conversion to GIF/SVG for GitHub embedding. |
| metadata | {"internal":true} |
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
brew install asciinema
cargo install --git https://github.com/asciinema/agg
npm install -g svg-term-cli
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
clear
export PS1='$ '
export TERM=xterm-256color
Terminal size: 100x24 (readable when scaled down)
3. Record
asciinema rec demo.cast --cols 100 --rows 24
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
agg demo.cast demo.gif
agg --speed 1.5 demo.cast demo.gif
agg --font-size 14 demo.cast demo.gif
Alternative - SVG (smaller files):
svg-term --in demo.cast --out demo.svg --window
5. Validate (Self-Validation)
Claude can self-validate demos using three approaches:
A. Automated Checks (run these first)
ls -lh demo.gif
head -1 demo.cast | jq '.duration // "check manually"'
B. Visual Validation (LLM-as-judge)
Extract a static frame for Claude to analyze:
svg-term --in demo.cast --out demo-preview.svg --at 15000
asciinema cat demo.cast | head -500 | freeze -o demo-preview.png
Then ask Claude to analyze using the Read tool on the image:
Validation prompt:
Analyze this terminal demo screenshot. Check:
1. Is the text readable (not too small/blurry)?
2. Is the command being demonstrated visible?
3. Is there any sensitive info (API keys, /Users/username paths)?
4. Does the terminal look clean (simple prompt, no clutter)?
5. Is the "aha moment" visible - what value does this demo show?
Rate: PASS or FAIL with specific issues.
C. Content Validation (parse .cast file)
The .cast file is JSON lines - validate the content programmatically:
grep '"i"' demo.cast | head -20
head -1 demo.cast | jq -r '.duration | floor'
grep -iE '(api.?key|password|secret|/Users/[a-z])' demo.cast && echo "WARNING: Sensitive data found!"
D. Full Validation Checklist
After running the above, verify:
6. Embed in PR
## Demo

*Shows: [one-sentence description of what the demo shows]*
Store demos in docs/demos/ or assets/ directory.
Quick Reference
| Setting | Recommended Value |
|---|
| Duration | 20-30 seconds |
| Terminal size | 100x24 |
| Speed multiplier | 1.0-1.5x |
| Target file size | < 2MB ideal, < 5MB max |
| Font size (agg) | 14-16 |
Common Mistakes
| Mistake | Fix |
|---|
| Demo too long | Script it first, show ONE thing |
| Text unreadable | Use --font-size 14+, terminal 100x24 |
| File too large | Use svg-term-cli instead, or increase speed |
| Cluttered terminal | Clean PS1, clear history, hide paths |
| No context in PR | Add one-line description below GIF |
File Organization
docs/demos/
├── feature-name.gif # The demo
├── feature-name.cast # Source recording (optional, for re-rendering)
└── README.md # Recording instructions for future maintainers