Back to Details

agent-log-gif

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

agent-log-gif

agent-log-gif

Convert Claude Code and Codex session logs into animated terminal replays (GIF, MP4, AVIF).
将Claude Code和Codex会话日志转换为带动画的终端回放（GIF、MP4、AVIF格式）。

Prerequisites

前提条件

This skill uses 
uvx
to run agent-log-gif without permanent installation. Before doing anything else:
bash
uvx --version
If 
uvx
is not found, help the user install 
uv
. Check their platform and available tools:
  • macOS with Homebrew (check 
    brew --version
    ): 
    brew install uv
  • macOS/Linux without Homebrew: 
    curl -LsSf https://astral.sh/uv/install.sh | sh
  • Windows (PowerShell): 
    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Tell the user to restart their terminal after installing.
Do not proceed until 
uvx
is confirmed working.
此技能使用
uvx
来运行agent-log-gif，无需永久安装。在进行任何操作之前，请先执行：
bash
uvx --version
如果未找到
uvx
，请帮助用户安装
uv
。根据用户的平台和可用工具选择对应方式：
  • 使用Homebrew的macOS（先检查
    brew --version
    ）：
    brew install uv
  • 不使用Homebrew的macOS/Linux：
    curl -LsSf https://astral.sh/uv/install.sh | sh
  • Windows（PowerShell）：
    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
告知用户安装完成后重启终端。 在确认
uvx
可以正常工作之前，不要进行后续操作。

Discovering options and session sources

查看选项与会话源

Run 
--help
to discover current options AND detect available session sources. The help output includes a "Sessions:" line showing which sources (Claude Code, Codex, or both) are detected on this machine:
bash
uvx agent-log-gif json --help
Use this output to understand available flags — the tool evolves, so always check rather than assuming options from memory. The main help also shows tool availability:
bash
uvx agent-log-gif --help
gets help on all available options; note that the 
local
option is for an interactive mode you won't be able to navigate inside a skill.
运行
--help
命令可查看当前选项并检测可用的会话源。帮助输出中会包含“Sessions:”一行，显示当前机器上检测到的源（Claude Code、Codex或两者都有）：
bash
uvx agent-log-gif json --help
请参考此输出了解可用的参数——该工具会不断更新，因此请始终通过此方式查看，不要凭记忆假设选项。主帮助信息也会显示工具的可用功能：
bash
uvx agent-log-gif --help
此命令可查看所有可用选项；请注意，
local
选项用于交互模式，在技能内部无法操作该模式。

Finding sessions

查找会话

Listing available sessions

列出可用会话

Use the built-in 
--list
flag to browse recent sessions — it shows dates, sizes, summaries, and full file paths:
bash
undefined
使用内置的
--list
标记可浏览最近的会话——会显示会话日期、大小、摘要和完整文件路径：
bash
undefined

List recent Claude Code sessions

列出最近的Claude Code会话

uvx agent-log-gif json --list=claude
uvx agent-log-gif json --list=claude

List recent Codex sessions

列出最近的Codex会话

uvx agent-log-gif json --list=codex

Run whichever source(s) the `--help` output showed as detected. If both exist, list both and let the user pick. The output includes full file paths ready to use in the next command.
uvx agent-log-gif json --list=codex

运行`--help`输出中显示的已检测到的源对应的命令。如果两者都存在，可列出所有会话并让用户选择。输出会包含可直接用于下一条命令的完整文件路径。

Keyword search

关键词搜索

When the user mentions a topic or keyword, use the built-in search command:
bash
undefined
当用户提及某个主题或关键词时，使用内置的搜索命令：
bash
undefined

Search both Claude Code and Codex sessions

搜索Claude Code和Codex会话

uvx agent-log-gif search "keyword"
uvx agent-log-gif search "keyword"

Search only one source

仅搜索单个源

uvx agent-log-gif search "keyword" --source claude uvx agent-log-gif search "keyword" --source codex

This returns matching sessions with dates, sizes, summaries, and full file paths.
uvx agent-log-gif search "keyword" --source claude uvx agent-log-gif search "keyword" --source codex

此命令会返回匹配的会话，包含日期、大小、摘要和完整文件路径。

Direct file path

直接使用文件路径

If the user provides a path or the session is already identified, skip discovery and go straight to generation.
如果用户提供了路径或会话已确定，可跳过发现步骤，直接生成动画。

Generating the animation

生成动画

bash
uvx agent-log-gif json <session-path> -o <output-path> [options] --open
bash
uvx agent-log-gif json <session-path> -o <output-path> [options] --open

Sensible defaults

合理的默认设置

  • Format: GIF unless the user asks for video
  • Chrome style: Detect the user's OS and match:
    • macOS → 
      --chrome mac
    • Linux → 
      --chrome linux
    • Other/unsure → 
      --chrome mac
  • Color scheme: Dracula (default) — don't add 
    --color-scheme
    unless the user has a preference
  • Output path: Descriptive name in the current directory, like 
    session-replay.gif
  • Turns: Let the default cap (20) apply unless requested otherwise
  • --open: Always include so the user sees the result
  • 格式：默认使用GIF，除非用户要求视频格式
  • Chrome样式：检测用户的操作系统并匹配对应样式：
    • macOS → 
      --chrome mac
    • Linux → 
      --chrome linux
    • 其他/不确定 → 
      --chrome mac
  • 配色方案：默认使用Dracula配色——除非用户有偏好，否则不要添加
    --color-scheme
    参数
  • 输出路径：在当前目录下生成描述性名称的文件，例如
    session-replay.gif
  • 轮次：使用默认上限（20），除非用户另有要求
  • --open：始终添加此参数，以便用户查看结果

Walking through options

选项说明

If the user wants to customize, present the key choices conversationally. Refer to the 
--help
output for the current set of options, but the main ones are typically:
  1. Format: GIF (default), MP4, AVIF
  2. Window frame style (
    --chrome
    )
  3. Color theme (
    --color-scheme
    ) — 480+ terminal color schemes available
  4. What to show (
    --show
    ) — conversation only, tool calls, everything
  5. Size (
    --cols
    , 
    --rows
    , 
    --font-size
    )
Build the command from their choices and confirm before running.
如果用户想要自定义设置，可以对话式地呈现关键选项。请参考
--help
输出获取当前的选项列表，主要选项通常包括：
  1. 格式：GIF（默认）、MP4、AVIF
  2. 窗口框架样式（
    --chrome
    ）
  3. 配色主题（
    --color-scheme
    ）——支持480多种终端配色方案
  4. 显示内容（
    --show
    ）：仅对话、仅工具调用、全部内容
  5. 尺寸（
    --cols
    、
    --rows
    、
    --font-size
    ）
根据用户的选择构建命令，并在运行前确认。

Example commands

示例命令

bash
undefined
bash
undefined

Basic — auto-opens result

基础用法——自动打开结果

uvx agent-log-gif json ~/.claude/projects/.../session.jsonl -o demo.gif --open
uvx agent-log-gif json ~/.claude/projects/.../session.jsonl -o demo.gif --open

Customized

自定义设置

uvx agent-log-gif json session.jsonl -o replay.gif --chrome linux --color-scheme Nord --show tools --turns 5
uvx agent-log-gif json session.jsonl -o replay.gif --chrome linux --color-scheme Nord --show tools --turns 5

Interactive picker (shortcut when no search needed)

交互式选择器（无需搜索时的快捷方式）

uvx agent-log-gif
undefined
uvx agent-log-gif
undefined

Creating synthetic sessions from scratch

从零开始创建合成会话

Users may want a GIF that illustrates a hypothetical conversation rather than replaying an existing session — for demos, docs, tutorials, or marketing. You can generate a JSONL file from scratch and feed it to the tool.
用户可能需要一个展示假设性对话的GIF，而非回放现有会话——用于演示、文档、教程或营销。你可以从零开始生成JSONL文件，然后将其输入到工具中。

JSONL format

JSONL格式

Each line is a JSON object. The first line is a summary, then a stream of 
user
and 
assistant
messages. Here's a minimal example with a tool call:
jsonl
{"type":"summary","summary":"Demo: adding a test"}
{"type":"user","timestamp":"2025-01-15T10:00:00.000Z","message":{"role":"user","content":"Add a test for the login endpoint"}}
{"type":"assistant","timestamp":"2025-01-15T10:00:08.000Z","message":{"role":"assistant","content":[{"type":"text","text":"I'll create a test for the login endpoint."},{"type":"tool_use","id":"toolu_01","name":"Write","input":{"file_path":"tests/test_login.py","content":"def test_login():\n    response = client.post('/login', json={'user': 'admin', 'pass': 'secret'})\n    assert response.status_code == 200\n"}}]}}
{"type":"user","timestamp":"2025-01-15T10:00:12.000Z","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_01","content":"File written successfully"}]}}
{"type":"assistant","timestamp":"2025-01-15T10:00:18.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Done! The test is ready. Run pytest to verify it passes."}]}}
Note: tool results use 
type: "user"
— this is the API protocol, not human input. The harness sends tool output back to the model as user messages.
每一行都是一个JSON对象。第一行是摘要，后续是
user
和
assistant
消息流。以下是包含工具调用的最简示例：
jsonl
{"type":"summary","summary":"Demo: adding a test"}
{"type":"user","timestamp":"2025-01-15T10:00:00.000Z","message":{"role":"user","content":"Add a test for the login endpoint"}}
{"type":"assistant","timestamp":"2025-01-15T10:00:08.000Z","message":{"role":"assistant","content":[{"type":"text","text":"I'll create a test for the login endpoint."},{"type":"tool_use","id":"toolu_01","name":"Write","input":{"file_path":"tests/test_login.py","content":"def test_login():\n    response = client.post('/login', json={'user': 'admin', 'pass': 'secret'})\n    assert response.status_code == 200\n"}}]}}
{"type":"user","timestamp":"2025-01-15T10:00:12.000Z","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_01","content":"File written successfully"}]}}
{"type":"assistant","timestamp":"2025-01-15T10:00:18.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Done! The test is ready. Run pytest to verify it passes."}]}}
注意：工具结果使用
type: "user"
——这是API协议的要求，并非人类输入。工具会将工具输出作为用户消息发送回模型。

Key rules

关键规则

  • Timestamps drive the "Churned for Xs" duration display — space them realistically (5-30s between user and assistant)
  • Tool calls need matching 
    tool_result
    entries with the same 
    tool_use_id
  • User messages: plain string for typed input, or 
    [{"type":"tool_result",...}]
    array for tool results
  • Assistant messages: always a content array with 
    {"type":"text"}
    and/or 
    {"type":"tool_use"}
    blocks
  • Tool calls and results are hidden by default — use 
    --show tools
    or 
    --show all
    to include them
  • Keep messages concise — long text gets elided in the animation
  • 时间戳决定了“已处理X秒”的显示时长——请合理设置间隔（用户与助手消息之间间隔5-30秒）
  • 工具调用需要匹配带有相同
    tool_use_id
    的
    tool_result
    条目
  • 用户消息：输入内容为纯字符串，或工具结果为
    [{"type":"tool_result",...}]
    数组
  • 助手消息：始终为包含
    {"type":"text"}
    和/或
    {"type":"tool_use"}
    块的内容数组
  • 工具调用和结果默认隐藏——使用
    --show tools
    或
    --show all
    参数可显示它们
  • 请保持消息简洁——长文本在动画中会被省略

Workflow

工作流程

  1. Write the JSONL to a temp file
  2. Render with 
    uvx agent-log-gif json <path> -o demo.gif --open
  3. Adjust content/timing and re-render until it looks right
  1. 将JSONL写入临时文件
  2. 使用
    uvx agent-log-gif json <path> -o demo.gif --open
    命令渲染
  3. 调整内容/时间，重新渲染直到效果满意

Important notes

重要说明

  • Always use 
    uvx agent-log-gif
    — it handles installation automatically
  • MP4/AVIF require ffmpeg — help the user install it if needed
  • Session file URLs also work: 
    uvx agent-log-gif json https://...
  • Codex sessions are auto-detected by the tool's parser — no special flags needed
  • 请始终使用
    uvx agent-log-gif
    ——它会自动处理安装
  • 生成MP4/AVIF需要ffmpeg——如果需要，请帮助用户安装
  • 会话文件的URL也可使用：
    uvx agent-log-gif json https://...
  • 工具的解析器会自动检测Codex会话——无需特殊参数