How to Record a Terminal GIF

Step-by-step guide to recording terminal sessions as GIF animations using VHS, asciinema, and AgentGIF CLI.

1. Prerequisites

To record terminal GIFs, you need:

VHS — a terminal recorder by Charm that converts scripted terminal sessions into GIFs
ttyd — a terminal web server (VHS dependency, installed automatically on macOS)
ffmpeg — for video encoding (installed automatically on macOS)

VHS works by reading a .tape file that describes keystrokes, commands, and timing — then it replays those actions in a virtual terminal and captures the output as a GIF.

2. Install VHS

Platform	Install Command
macOS	`brew install vhs`
Ubuntu/Debian	`sudo mkdir -p /etc/apt/keyrings && curl -fsSL https://repo.charm.sh/apt/gpg.key \| sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg && echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" \| sudo tee /etc/apt/sources.list.d/charm.list && sudo apt update && sudo apt install vhs`
Arch Linux	`yay -S vhs`
Go	`go install github.com/charmbracelet/vhs@latest`

Verify the installation:

vhs --version

3. Create a Tape File

A tape file is a plain-text script that tells VHS what to type, when to wait, and what settings to use. Create a file called demo.tape:

Output demo.gif
Set Shell "bash"
Set FontSize 16
Set Width 1000
Set Height 580
Set Theme "Catppuccin Mocha"

Type "echo 'Hello, world!'"
Enter
Sleep 2s

Type "ls -la"
Enter
Sleep 3s

Core Commands

Command	Description	Example
`Output`	Set the output file path	`Output "demo.gif"`
`Type`	Type text (simulates keystrokes)	`Type "git status"`
`Enter`	Press Enter	`Enter`
`Sleep`	Wait for a duration	`Sleep 2s`
`Ctrl+C`	Send keyboard shortcut	`Ctrl+C`
`Hide`	Stop recording (for setup)	`Hide`
`Show`	Resume recording	`Show`

4. Configure Settings

Put Set commands at the top of your tape file, before any Type commands.

Recommended Settings for AgentGIF

Set Shell "zsh"
Set FontSize 15
Set Width 1000
Set Height 580
Set Padding 20
Set Theme "Catppuccin Mocha"
Set TypingSpeed 50ms
Set CursorBlink false

All Available Settings

Setting	Default	Description
`Shell`	`"bash"`	Shell to use (bash, zsh, fish, sh)
`FontSize`	`14`	Font size in pixels
`Width`	`800`	Terminal width in pixels
`Height`	`600`	Terminal height in pixels
`Padding`	`0`	Padding around terminal
`Theme`	`"default"`	Color theme (see theme gallery)
`TypingSpeed`	`50ms`	Delay between keystrokes
`Framerate`	`50`	GIF frames per second
`PlaybackSpeed`	`1`	Playback speed multiplier
`CursorBlink`	`true`	Show blinking cursor
`LetterSpacing`	`0`	Extra letter spacing
`LineHeight`	`1.0`	Line height multiplier

Themes

VHS ships with 44 built-in themes. Popular choices for developer documentation:

Theme	Style
Catppuccin Mocha	Warm dark (pastel accents)
Dracula	Dark purple
Tokyo Night	Blue-tinted dark
Nord	Arctic blue
One Dark	Atom-inspired dark
Solarized Dark	Classic dark with warm tones
Monokai	Sublime Text-inspired

Browse all themes with live previews: Theme Gallery.

5. Record the GIF

vhs demo.tape

VHS opens a headless browser, replays the tape, and saves the GIF. Typical recording takes 10-30 seconds.

Preview before uploading:

# macOS
open demo.gif

# Linux
xdg-open demo.gif

6. Optimize File Size

AgentGIF accepts GIFs up to 10 MB, but smaller files load faster. Tips for keeping GIF size down:

Technique	Impact
Reduce dimensions (`Width 800`)	Significant — halving width quarters the file size
Lower framerate (`Framerate 30`)	Moderate — reduces frames by 40%
Shorter recording	Significant — aim for 5-15 seconds
Use `PlaybackSpeed 1.5`	Moderate — fewer total frames
Disable cursor blink (`CursorBlink false`)	Small — fewer unique frames
Solid background (avoid transparency)	Small — better GIF compression

For the best balance of quality and size, the recommended settings above produce GIFs around 100-300 KB for a 10-second recording.

7. Upload to AgentGIF

Upload via CLI (fastest):

agentgif upload demo.gif \
  --title "Git Interactive Rebase" \
  --command "git rebase -i HEAD~3" \
  --tags git,rebase \
  --open

Or upload via the web interface — drag and drop the GIF file.

Including a cast file enables the AI agent layer:

agentgif upload demo.gif --cast demo.cast --title "My Demo"

8. Advanced Tape Features

Hide/Show for Setup

Use Hide/Show to run setup commands without recording them:

Hide
Type "cd /tmp/demo-project"
Enter
Type "mkdir -p src"
Enter
Show

# Now recording starts
Type "ls -la"
Enter
Sleep 2s

Multiple Output Formats

VHS can output multiple formats simultaneously:

Output demo.gif
Output demo.mp4
Output demo.webm

Environment Variables

Set Shell "bash"
Type "export PS1='$ '"
Enter
Hide
Sleep 500ms
Show

Keyboard Shortcuts

Ctrl+C     # Cancel current command
Ctrl+L     # Clear screen
Ctrl+D     # EOF / exit
Tab        # Tab completion
Up         # Previous command
Escape     # Escape key

9. Alternative Recording Tools

Tool	Output	Pros	Cons
VHS	GIF, MP4, WebM	Scripted, reproducible, themes	Requires setup
asciinema	.cast	Live recording, small files	No GIF output (needs conversion)
Terminalizer	GIF	Live recording, YAML config	Large file sizes
Peek	GIF, WebM	GUI screen recorder	Not terminal-specific

We recommend VHS for scripted demos (reproducible, version-controllable) and asciinema + VHS conversion for live recordings.

← All Guides · Embed GIFs in GitHub README →