agent-log-gif 0.1.4

Convert Claude Code session files to animated gifs and videos. Fork of https://github.com/simonw/claude-code-transcripts.

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)
  --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.