agent-log-gif

Turn your Claude Code and Codex sessions into animated terminal-style replay GIFs or videos. Share them on Reddit, Slack, etc.

^{With apologies to Summer Yue.}

Less fun but more usefully: use agent session videos to do retrospective reviews; include cool Claude demos in slide decks.

Supports Claude Code and Codex sessions out of the box.

Windows UI + Codex example

Quick start

Try it in the browser with the magic of WASM.

Run the CLI:

uvx agent-log-gif

Or pick a specific session from disk:

uvx agent-log-gif json ~/.claude/projects/<project>/<session>.jsonl

Help on all options:

uvx agent-log-gif json --help

To install permanently:

uv tool install agent-log-gif

Or to install as a Skill you can ask your agent to use for you:

npx skills add ysamlan/agent-log-gif

Claude/Codex skill

agent-log-gif includes an agent-log-gif Skill that lets Claude Code / Codex find your sessions and generate animations for you conversationally. Copy the skills/agent-log-gif folder it into ~/.claude/skills/, or install automatically via skills.sh:

npx skills add ysamlan/agent-log-gif

Then ask Claude things like "make a gif of my last coding session" or "find the session where I worked on auth and make an mp4 showing tool calls," or run /agent-log-gif inside Claude Code ($agent-log-gif in Codex).

Optional tools

For MP4/AVIF output, install ffmpeg using your system package manager (brew install ffmpeg, choco install ffmpeg, apt install ffmpeg, etc.).

For AVIF, your ffmpeg build must include an AV1 encoder. agent-log-gif prefers libsvtav1 and falls back to libaom-av1.

ffmpeg -encoders | rg 'av1|svt|aom'

Optimized GIFs

GIF optimization is done automatically via gifsicle using gifsicle-bin. Very large GIFs will skip automatic optimization to avoid hanging/crashing gifsicle.

Usage

Convert a session file

# GIF (default)
agent-log-gif json session.jsonl

# Animated AVIF
agent-log-gif json session.jsonl --format avif

# MP4 with (optional) background music
agent-log-gif json session.jsonl --format mp4 --music track.mp3 --loop-music

# Specify output file
agent-log-gif local -o out.gif

Pick from local sessions

agent-log-gif                  # interactive picker, opens result

Turn selection

Sessions default to 20 turns max. Adjust with --turns:

agent-log-gif json session.jsonl --turns 5      # first 5 turns
agent-log-gif json session.jsonl --turns 3,8    # turns 3 through 8

Music (MP4 only)

agent-log-gif json session.jsonl -o demo.mp4 --format mp4 --music track.mp3
agent-log-gif json session.jsonl -o demo.mp4 --format mp4 --music track.mp3 --loop-music

Window chrome

Default is macOS-26-like with rounded corners and traffic-light buttons. Choose a different style:

agent-log-gif json session.jsonl --chrome none         # no window frame
agent-log-gif json session.jsonl --chrome mac          # macOS, rounded corners (default)
agent-log-gif json session.jsonl --chrome mac-square   # macOS, square corners
agent-log-gif json session.jsonl --chrome windows      # Windows 11
agent-log-gif json session.jsonl --chrome linux        # GNOME/Ubuntu

For dark terminal themes embedded on a light page, you can set the outer canvas color behind the rounded macOS corners:

agent-log-gif json session.jsonl --chrome mac --canvas-bg "#FFFFFF"

Color scheme

480+ terminal color schemes bundled from iTerm2-Color-Schemes. Default is Dracula.

agent-log-gif json session.jsonl --color-scheme "Catppuccin Mocha"

Custom font

Default is DejaVu Sans Mono (bundled). Override with any TTF:

agent-log-gif json session.jsonl --font /path/to/MyFont.ttf

Supported session formats

• Claude Code JSONL files (~/.claude/projects/)
• Codex JSONL session files (~/.codex/sessions/)
• URLs to any of the above

Web sessions

Warning

The web commands are broken right now due to changes to the unofficial and undocumented APIs that these commands were using. See this issue in simonw/claude-code-transcripts for details.

agent-log-gif web                       # interactive session picker
agent-log-gif web SESSION_ID            # specific session
agent-log-gif web --repo owner/repo     # filter by repo

On macOS, credentials are auto-detected from your keychain. On other platforms, provide --token and --org-uuid.

All options

agent-log-gif json [OPTIONS] [FILE]

  -o, --output PATH            Output file path (default: <input>.<format>)
  --list [claude|codex]        List recent sessions instead of converting
  --format [gif|mp4|avif]      Output format (default: gif)
  --turns TEXT                 N for first N turns, M,N for range
  --music PATH                 Music track for MP4
  --loop-music                 Loop music if shorter than video
  --chrome STYLE               Window chrome: none|mac|mac-square|windows|linux
  --canvas-bg TEXT             Outer canvas color outside rounded macOS corners
  --color-scheme NAME          Terminal color scheme (e.g. Dracula, Nord)
  --font PATH                  Custom TTF font file
  --cols INT                   Terminal width in columns (default: 80)
  --rows INT                   Terminal height in rows (default: 18)
  --font-size INT              Font size in pixels (default: 16)
  --show TYPES                 Extra content: tools, calls, thinking, all
  --speed FLOAT                Typing speed multiplier (default: 1.0)
  --spinner-time FLOAT         Spinner duration multiplier (default: 1.0)
  --thinking-verbs TEXT        Custom spinner verbs (comma-separated)
  --shimmer / --no-shimmer     Loading line shimmer effect (default: on)
  --colors INT                 GIF palette size, 2-256 (default: 256)
  --parallel INT               Rendering workers (0=auto, 1=off, 2+=explicit)
  --gifsicle / --no-gifsicle   gifsicle post-processing (default: on)
  --lossy INT                  Gifsicle lossy level 0-200 (default: 80). 0=off.
  --loop / --no-loop           Loop GIF infinitely (default: on)
  --loop-offset INT             Start GIF at this % (0-100) into the animation
  --open / --no-open           Open result in default viewer

agent-log-gif search KEYWORD [--source claude|codex]

Credits

Session parsing logic originally based on Simon Willison's claude-code-transcripts.
Gifsicle by Eddie Kohler (GPLv2 license) is used for (optional) gif optimization.
gifsicle-bin provides auto-installation of arms-length gifsicle binaries (native wheels) and WASM builds (GitHub Release assets) for optimization.
Gifsicle WASM build approach based on Simon Willison's work.
Color schemes from iTerm2-Color-Schemes by Mark Badolato (MIT license).

Development

See CONTRIBUTING.md for setup and guidelines.