Generating Lightweight Terminal GIFs with asciinema, agg, and gifsicle

Ethan Moore — Mon, 26 Oct 2026 14:17:48 +0000

When building small web tools and command-line utilities, I frequently need to demonstrate workflows directly inside project README files and documentation sites. Recording the screen with a generic GUI capture tool often yields bulky files: a 10-second terminal clip can easily balloon to several megabytes, stutter on mobile connections, and introduce blurry text compression artifacts.

To keep documentation snappy, I rely on a pipeline of standard open-source utilities: asciinema to record timing data, agg (asciinema gif generator) to render crisp frames, ffmpeg for palette calculations when fine-tuning, and gifsicle for lossy payload reduction. This workflow keeps terminal recordings sharp and, for short clips, often gets them down to a few hundred kilobytes.

Step 1: Record Text Streams with asciinema

Instead of capturing screen pixels, asciinema records the raw terminal output along with its timing. A pause costs only a timestamp, not a stream of identical frames.

Install asciinema via your package manager and start recording to a local .cast file:

asciinema rec demo.cast

Run your commands naturally. When you finish, press Ctrl+D or type exit.

Before moving to the next step, you can edit demo.cast with any text editor. It is newline-delimited JSON: a header line, then one event per line. You can trim stray events by hand, but for long hesitations it is easier to let tools cap them: asciinema rec --idle-time-limit 2 while recording, or agg's --idle-time-limit when rendering (agg defaults to 5 seconds).

Step 2: Render Crisp Terminal Frames with agg

The agg utility converts .cast timing data into an animated GIF. Unlike a screen recorder, it renders the text itself from a font onto a fixed character grid, using a terminal color theme, so the glyphs come out clean.

Install agg with Cargo or grab a prebuilt binary from its GitHub releases page, then generate a baseline GIF:

agg --fps-cap 12 \
    --font-size 14 \
    --theme monokai \
    --speed 1.2 \
    --rows 18 \
    --cols 80 \
    demo.cast raw.gif

A few flags make an enormous difference here:

--fps-cap 12: agg's default cap is 30 fps. For a text terminal, around 12 fps still looks smooth and produces fewer frames.
--speed 1.2: Speeding up execution slightly keeps visitors engaged without making keystrokes unreadable.
--rows and --cols: Override the recorded terminal size, which keeps the output dimensions predictable. Record at the same size, or long lines will wrap differently.

Step 3: Palette Control with ffmpeg

A GIF frame can use at most 256 colors. If your terminal uses smooth syntax highlighting or gradient progress bars, default conversion algorithms will produce noisy color banding.

When I need tighter control over color mapping than agg provides out of the box, I render a lossless intermediate file or pass the frames through ffmpeg using a two-pass palette generator:

ffmpeg -i raw.gif -vf "fps=12,palettegen=max_colors=64:reserve_transparent=0" palette.png

ffmpeg -i raw.gif -i palette.png -lavfi "fps=12 [x]; [x][1:v] paletteuse=dither=bayer:bayer_scale=3" palette_mapped.gif

By capping max_colors to 64 (or 128 for complex themes) and applying an ordered Bayer dither, the file usually shrinks. Terminal backgrounds stay flat, which gives the subsequent LZW compression algorithm repetitive pixel runs to compress efficiently.

Step 4: Final Shrinkage with gifsicle

The raw output from rendering engines often retains duplicate pixels and unoptimized frame metadata. gifsicle is the standard tool for stripping overhead, dropping redundant frame data, and applying lossy quantization.

Run this compression pass on your rendered GIF:

gifsicle -O3 \
         --lossy=80 \
         --colors 64 \
         --no-extensions \
         raw.gif -o demo_optimized.gif

Here is what these arguments do:

-O3: The highest optimization level. Like the lower levels it stores only the changed part of each frame, but it tries several methods and keeps the smallest (slower to run).
--lossy=80: Allows small visual noise in exchange for massive file savings. gifsicle's docs suggest values around 30 to 200; on dark terminal backgrounds 60 to 80 is usually hard to notice. Compare before and after on your own clip.
--colors 64: Reduces the palette to 64 colors. A smaller palette means fewer bits per pixel and longer repeated runs, so LZW compresses better.
--no-extensions: Drops non-essential extension blocks such as comments and app metadata. gifsicle still keeps the loop setting.

Baseline Reference Numbers

Across my open-source projects, I aim for these constraints:

Target size: Under 800 KB for a 15-second clip.
Frame rate: 12 fps (never exceed 15 fps for CLI tooling).
Color count: 32 to 64 colors for standard mono-like shells; 128 colors maximum for rich terminal UIs.
Dimensions: 80 columns by 16 to 24 rows, agg font size 14.