← BACK TO THE HOMEPAGE

Nov 21, 2026 • 5 min read

Generating Crisp Terminal GIFs from Asciinema Files with agg

The Problem

Raw terminal recordings or screen captures often end up bloated, blurry, or poorly sized for documentation, READMEs, and blog posts. While .cast files recorded with asciinema are lightweight and crisp in a web player, many platforms, chat apps, and static site layouts require a self-contained animated GIF.

Instead of recording your screen with a video capture tool and manually converting or trimming frames, you can render .cast files directly into high-quality animated GIFs using agg (asciinema gif generator), backed by gifski for smooth frame timing and color rendering.

flowchart LR
    subgraph Recording["1. Capture Session"]
        Term["Terminal Session"] -->|"asciinema rec"| CastFile["agg-demo.cast"]
    end

    subgraph Rendering["2. Render GIF"]
        CastFile -->|"agg + options"| AggTool["agg CLI"]
        AggTool --> GifFile["demo.gif"]
    end
  • The example below uses a self-contained agg-demo.cast file in asciinema v2 format so you can test the exact input and output without recording a session first.

Technical Solution Overview

Generating a polished GIF works best as a two-step workflow: create a minimal agg-demo.cast input and verify a baseline GIF render, then tune visual geometry, color themes, and typography for your target layout.

flowchart LR
    Step1["Step 1: Sample agg-demo.cast
& Baseline GIF"] --> Step2["Step 2: Styled GIF
(Themes, Size & Typography)"]
  1. Save the following sample asciinema recording as agg-demo.cast:
TERMINAL_INPUT // BASH
{"version": 2, "width": 80, "height": 18, "title": "agg demo"}
[0.2, "o", "\u001b[1;32muser@host\u001b[0m:\u001b[1;34m~\u001b[0m$ "]
[0.8, "o", "echo \"Hello from agg\"\r\n"]
[1.0, "o", "Hello from agg\r\n"]
[1.3, "o", "\u001b[1;32muser@host\u001b[0m:\u001b[1;34m~\u001b[0m$ "]
[1.9, "o", "uname -s\r\n"]
[2.1, "o", "\u001b[36mLinux\u001b[0m\r\n"]
[2.4, "o", "\u001b[1;32muser@host\u001b[0m:\u001b[1;34m~\u001b[0m$ "]

Pro-Tip: Piping or Remote Recordings

  • You can pass a local .cast file, read from standard input (-), or point agg directly at an asciinema.org recording URL:
TERMINAL_INPUT // BASH
cat agg-demo.cast | agg - demo.gif
  • Use agg when you want deterministic, repeatable terminal GIFs for docs and tutorials without manual video editing.

Step 1: Sample agg-demo.cast and Baseline GIF

An asciinema v2 file is newline-delimited JSON: line 1 is a JSON object header with terminal dimensions and metadata, and each subsequent line is a [timestamp, event_code, data] array.

flowchart LR
    Cast["agg-demo.cast
(v2 header + 'o' events)"] -->|"agg agg-demo.cast demo.gif"| OutGif["demo.gif
(Baseline GIF)"]
  1. Confirm agg is installed and inspect its command-line options:
TERMINAL_INPUT // BASH
agg -h
  1. Render a baseline GIF from agg-demo.cast:
TERMINAL_INPUT // BASH
agg agg-demo.cast demo.gif

Expected Input & Output

  • Input (agg-demo.cast): An 80x18 asciinema recording ("width": 80, "height": 18) spanning ~2.4 seconds with ANSI color escape sequences (\u001b[1;32m, \u001b[1;34m, \u001b[36m) and "o" (output) events.
  • Output (demo.gif): An animated GIF playing the prompt, echo "Hello from agg", Hello from agg, uname -s, and Linux at real-time intervals using agg’s default settings (dracula theme and swash renderer).

Step 2: Customizing Themes, Dimensions, and Typography

To make terminal GIFs legible across high-DPI displays, documentation cards, and mobile viewports, explicitly configure layout geometry, color palettes, and text metrics.

flowchart LR
    Cast["agg-demo.cast"] --> Opts["--theme, --cols, --rows
--font-size, --line-height"] Opts --> StyledGif["polished.gif"]
  1. Color Themes (--theme): Override the default or embedded theme using built-in names such as asciinema, dracula, github-dark, github-light, gruvbox-dark, kanagawa, kanagawa-dragon, kanagawa-light, monokai, nord, solarized-dark, or solarized-light (or pass custom hex color triplets):
TERMINAL_INPUT // BASH
agg --theme github-dark agg-demo.cast demo-color.gif

Expected Output:

Demo

  1. Terminal Dimensions (--cols and --rows): By default, agg uses the width and height stored in the .cast header (80 and 18 in agg-demo.cast). Override --cols (columns) and --rows (rows) to match a target frame size:
TERMINAL_INPUT // BASH
agg --cols 96 --rows 22 agg-demo.cast demo-dimension.gif

Expected Output:

Demo

  1. Font Size and Line Height (--font-size and --line-height): Adjust --font-size (in pixels) for sharper text scaling and --line-height (multiplier relative to font size, default 1.4) to control vertical spacing between lines:
TERMINAL_INPUT // BASH
agg --font-size 20 --line-height 1.5 agg-demo.cast demo-font.gif

Expected Output:

Demo

  1. Combine Options for a Production GIF: Put theme, dimensions, font sizing, and playback pacing together in a single command:
TERMINAL_INPUT // BASH
agg \
  --theme nord \
  --cols 96 \
  --rows 22 \
  --font-size 20 \
  --line-height 1.45 \
  --speed 1.25 \
  --idle-time-limit 2 \
  agg-demo.cast polished.gif

Expected Output:

Demo

Note: Overriding --cols and --rows can reflow long lines or alter full-screen TUIs compared to how they looked during recording, so preview the resulting GIF to verify line wrapping. Larger --font-size values also increase pixel dimensions and file size.

Key agg Options Reference

Option Purpose Example / Notes
--theme Sets built-in or custom hex color palette --theme dracula, monokai, nord, github-light
--cols Overrides terminal width in columns --cols 100 (defaults to recording header)
--rows Overrides terminal height in rows --rows 30 (defaults to recording header)
--font-size Sets rendered terminal font size in pixels --font-size 20 (higher values = crisper, larger GIF)
--line-height Sets vertical row spacing multiplier --line-height 1.4 (default is 1.4)
--font-family Specifies monospace font list --font-family "JetBrains Mono,Fira Code"
--speed & --idle-time-limit Adjusts playback rate and caps pauses --speed 1.5 --idle-time-limit 2

Conclusion

Using a sample agg-demo.cast file and agg lets you reproduce terminal GIFs deterministically while keeping your source asciinema recording lightweight and editable in plain text. Tuning --theme, --cols, --rows, --font-size, and --line-height ensures your commands and outputs stay crisp and legible across documentation layouts.

Whether you’re documenting CLI workflows, building technical blog posts, or sharing quick command demos, agg gives you scriptable control over terminal presentation from a single .cast file.