Convert asciicast terminal recordings (.cast) to animated GIF using agg (asciinema gif generator). Use this skill whenever the user wants to convert a .cast file to GIF, create animated terminal GIFs for documentation or READMEs, or needs a GIF from a terminal recording. Trigger when the user mentions agg, asciicast to GIF, terminal GIF, cast to GIF, or wants to generate a GIF from an asciinema recording. Also trigger when the user wants to customize terminal GIF appearance (themes, fonts, speed).
Convert asciicast v2 recordings (.cast files) to high-quality animated GIFs with agg. Uses gifski for optimized output with accurate frame timing.
# Homebrew
brew install agg
# Cargo (requires Rust 1.85+)
cargo install --git https://github.com/asciinema/agg
# Docker
docker run --rm -v $PWD:/data ghcr.io/asciinema/agg demo.cast demo.gif
Pre-compiled binaries (x86_64, aarch64, arm) on the releases page.
| Task | Command |
|---|---|
| Basic conversion | agg demo.cast demo.gif |
| From URL | agg https://asciinema.org/a/569727.cast demo.gif |
| From stdin | cat demo.cast | agg - demo.gif |
| 2x speed | agg --speed 2 demo.cast demo.gif |
| Cap idle time | agg --idle-time-limit 2 demo.cast demo.gif |
| Custom theme | agg --theme monokai demo.cast demo.gif |
| Custom font/size | agg --font-size 20 --font-family "Fira Code" demo.cast demo.gif |
| No loop | agg --no-loop demo.cast demo.gif |
| Override terminal size | agg --cols 100 --rows 30 demo.cast demo.gif |
| Quiet mode | agg -q demo.cast demo.gif |
| Record + convert | asciinema rec demo.cast && agg demo.cast demo.gif |
| With termsvg | termsvg rec demo.cast && agg demo.cast demo.gif |
agg [OPTIONS] <INPUT> <OUTPUT>
<INPUT> is a .cast file path, URL (including asciinema.org URLs), or - for stdin. <OUTPUT> is the GIF file path.
agg --speed 2 demo.cast demo.gif # 2x playback speed
agg --speed 0.5 demo.cast demo.gif # half speed
agg --idle-time-limit 2 demo.cast demo.gif # cap pauses at 2 seconds
agg --last-frame-duration 5 demo.cast demo.gif # hold last frame for 5s
agg --fps-cap 15 demo.cast demo.gif # lower FPS = smaller file
agg --no-loop demo.cast demo.gif # play once, don't loop
Built-in themes via --theme:
| Theme | Description |
|---|---|
dracula | Dracula (default) |
asciinema | asciinema default palette |
github-dark | GitHub dark mode |
github-light | GitHub light mode |
monokai | Monokai |
nord | Nord |
solarized-dark | Solarized Dark |
solarized-light | Solarized Light |
gruvbox-dark | Gruvbox Dark |
kanagawa | Kanagawa |
kanagawa-dragon | Kanagawa Dragon |
kanagawa-light | Kanagawa Light |
Custom theme — pass comma-separated hex triplets (no #):
# 10 values: bg, fg, color0-7
agg --theme 282a36,f8f8f2,282a36,f92672,a6e22e,f4bf75,66d9ef,ae81ff,a1efe4,f8f8f2 demo.cast demo.gif
# 18 values: bg, fg, color0-7, bright0-7
agg --theme 282a36,f8f8f2,282a36,f92672,a6e22e,f4bf75,66d9ef,ae81ff,a1efe4,f8f8f2,75715e,f92672,a6e22e,f4bf75,66d9ef,ae81ff,a1efe4,f9f8f5 demo.cast demo.gif
If the .cast file embeds a theme, agg uses it automatically. --theme overrides embedded themes.
agg --font-size 20 demo.cast demo.gif
agg --font-family "Fira Code" demo.cast demo.gif
agg --font-dir ~/fonts demo.cast demo.gif # additional font directory
agg --line-height 1.6 demo.cast demo.gif
Default font search order: JetBrains Mono, Fira Code, SF Mono, Menlo, Consolas, DejaVu Sans Mono, Liberation Mono. System fonts are searched automatically. DejaVu Sans and Noto Emoji are added as fallbacks for symbols and emoji.
agg --renderer resvg demo.cast demo.gif # default, supports color emoji
agg --renderer fontdue demo.cast demo.gif # direct rasterization, monochrome emoji only
agg --cols 120 --rows 40 demo.cast demo.gif
| Option | Default | Description |
|---|---|---|
--speed | 1 | Playback speed multiplier |
--idle-time-limit | 5 | Max idle time in seconds |
--last-frame-duration | 3 | Last frame hold time in seconds |
--fps-cap | 30 | Max frames per second |
--no-loop | off | Disable GIF looping |
--theme | dracula | Color theme (named or custom hex) |
--font-family | JetBrains Mono fallback chain | Font family (comma-separated) |
--font-size | 16 | Font size in pixels |
--font-dir | — | Additional font directory (repeatable) |
--line-height | 1.4 | Line height multiplier |
--renderer | resvg | Rendering backend (resvg or fontdue) |
--cols | from recording | Override terminal width |
--rows | from recording | Override terminal height |
-v, --verbose | off | Verbose logging (stack for debug: -vv) |
-q, --quiet | off | Suppress output and progress bars |
asciinema rec or termsvg rec to record, then agg to convert — they all use the asciicast v2 format.--idle-time-limit 2 to trim dead time and keep GIFs short.--fps-cap (e.g., 15) for smaller file sizes when smooth animation isn't critical.--no-loop for GIFs that play once — useful for step-by-step demos.gifsicle --lossy=80 -k 128 -O2 -Okeep-empty demo.gif -o demo-opt.gif--last-frame-duration 5 gives viewers more time to read the final output before the GIF loops..cast files first: agg https://asciinema.org/a/569727.cast out.gif