# PR Demo

Use when creating animated demos (GIFs) for pull requests or documentation.

- Repository: https://github.com/mikeyobrien/ralph-orchestrator (3190 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mikeyobrien/ralph-orchestrator --skill pr-demo -g -a claude-code -y`
Codex: `npx skills add mikeyobrien/ralph-orchestrator --skill pr-demo -g -a codex -y`
Cursor: `npx skills add mikeyobrien/ralph-orchestrator --skill pr-demo -g -a cursor -y`
Gemini CLI: `npx skills add mikeyobrien/ralph-orchestrator --skill pr-demo -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add mikeyobrien/ralph-orchestrator`

## 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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

```bash
# 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:

```markdown
## 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

```bash
# 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

```bash
# 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

```bash
# 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
```

The rest: https://github.com/mikeyobrien/ralph-orchestrator/blob/HEAD/.claude/skills/pr-demo/SKILL.md