AI Agent-Readable GIFs — Machine Layer Documentation

The Problem

GIF images are opaque to AI agents. When a README contains a terminal demo GIF, an AI agent sees binary pixel data — it can't extract the commands, understand the output, or reference specific steps. This is a fundamental limitation of image-based documentation.

AgentGIF solves this by attaching structured, machine-readable data to every GIF.

Dual-Layer Architecture

Every GIF on AgentGIF has two layers that coexist at the same URL:

A human sees an animated terminal. An AI agent sees structured data: commands, output, timestamps, metadata, and embed codes.

Cast Files (Asciinema v2)

The cast file is the richest data source. It's an asciinema v2 recording with precise timestamps for every terminal event.

Accessing the Cast

curl -s https://agentgif.com/api/v1/gifs/{id}/cast/

Cast File Structure

Line 1 is a JSON header with terminal metadata:

{"version": 2, "width": 120, "height": 40, "timestamp": 1710000000, "env": {"SHELL": "/bin/zsh", "TERM": "xterm-256color"}}

Subsequent lines are event tuples:

[0.0, "o", "$ "]
[0.5, "o", "docker compose up -d\r\n"]
[1.2, "o", "\u001b[32mCreating network...\u001b[0m\r\n"]
[2.8, "o", "Container app-1  Started\r\n"]

Each tuple is [timestamp_seconds, event_type, data]:

• "o" — output event (text written to the terminal screen)
• "i" — input event (user keystrokes, if captured)
• Timestamps are in seconds from recording start
• Data may contain ANSI escape codes for colors

Parsing a Cast File

import json

# Read cast file
lines = cast_data.strip().split("\n")
header = json.loads(lines[0])
events = [json.loads(line) for line in lines[1:]]

# Extract all output text
output = "".join(data for ts, typ, data in events if typ == "o")

# Find commands (lines starting with $ or % prompt)
commands = [line for line in output.split("\n") if line.startswith("$ ")]

Transcripts

For simpler use cases, the transcript endpoint returns clean plain text:

curl -s https://agentgif.com/api/v1/gifs/{id}/transcript/

Transcripts strip ANSI escape codes, collapse whitespace, and present the terminal session as readable text. They're ideal for:

• Embedding in LLM context windows (minimal tokens)
• Full-text search indexing
• Generating documentation from recorded sessions
• Comparing terminal output across GIFs

.md Endpoints

Every page on AgentGIF has a Markdown variant. Append .md to any URL:

# GIF detail → structured summary
curl https://agentgif.com/@agentgif/docker-compose/.md

# Tag listing → all GIFs with this tag
curl https://agentgif.com/explore/tags/docker/.md

# Tool page → all GIFs for this CLI tool
curl https://agentgif.com/tools/git/.md

# Collection → ordered GIF list
curl https://agentgif.com/@agentgif/collections/devops-essentials/.md

The response is text/markdown; charset=utf-8 — clean, structured text that LLMs can parse directly.

JSON API

The REST API provides full structured data. No authentication needed for reads:

# Search for GIFs about a topic
curl -s "https://agentgif.com/api/v1/search/?q=kubernetes" | jq '.results[:3] | .[].title'

# Get full metadata for a specific GIF
curl -s "https://agentgif.com/api/v1/gifs/{id}/" | jq '{title, command, tags, gif_url}'

# Browse by tag
curl -s "https://agentgif.com/api/v1/tags/docker/gifs/" | jq '.count'

See the complete API Reference for all 30+ endpoints.

Content Discovery

AI agents can discover AgentGIF content through multiple channels:

Real-World Examples

Agent: "Find a Docker demo and explain the steps"

# 1. Search for Docker GIFs
curl -s "https://agentgif.com/api/v1/search/?q=docker+compose" | jq '.results[0].id'
# → "xK9mQ2pL"

# 2. Get the transcript
curl -s "https://agentgif.com/api/v1/gifs/xK9mQ2pL/transcript/"
# → $ docker compose up -d
#   Creating network...
#   Container app-1  Started

# 3. Agent can now explain: "The demo shows docker compose up -d,
#    which starts services in detached mode..."

Agent: "Add a demo GIF to a README"

# 1. Search for the right tool
curl -s "https://agentgif.com/api/v1/search/?q=ripgrep" | jq '.results[0] | {id, gif_url, title}'

# 2. Generate embed code
# → [![ripgrep demo](https://media.agentgif.com/ID.gif)](https://agentgif.com/ID)

Agent: "Compare two terminal tools"

# Get GIFs for both tools
curl -s "https://agentgif.com/api/v1/tags/grep/gifs/" | jq '.results[].command'
curl -s "https://agentgif.com/api/v1/tags/ripgrep/gifs/" | jq '.results[].command'

# Compare the transcripts to understand different syntax