AI Agent Integration

The Dual Layer Architecture

Traditional GIF hosting platforms serve images — binary blobs that AI agents can't interpret. AgentGIF solves this by attaching a machine layer to every GIF:

An AI agent can look at a GIF page and understand exactly what commands were run, what the output was, and how long each step took — all without OCR or computer vision.

.md Endpoints

Append .md to any AgentGIF URL to get a text/markdown response optimized for LLMs. This is the fastest way for an AI agent to understand what's on a page.

# GIF detail page
curl https://agentgif.com/@agentgif/docker-compose/.md

# Tag page
curl https://agentgif.com/explore/tags/git/.md

# Guide page
curl https://agentgif.com/guides/how-to-record-terminal-gif/.md

# Search results
curl https://agentgif.com/search/.md

The response is a structured Markdown document with title, description, metadata, and relevant links. Content-Type: text/markdown; charset=utf-8.

Every page on AgentGIF supports the .md suffix — there are no dead ends for agents.

Cast Files (Asciinema v2)

The cast file is the richest machine layer. It's an asciinema v2 recording — a JSON header followed by timestamped terminal events:

GET /api/v1/gifs/{id}/cast/

Response format:

{"version": 2, "width": 120, "height": 40, "timestamp": 1710000000, "env": {"SHELL": "/bin/zsh", "TERM": "xterm-256color"}}
[0.5, "o", "$ docker compose up -d\r\n"]
[1.2, "o", "Creating network...\r\n"]
[2.8, "o", "Container app-1  Started\r\n"]
[3.1, "o", "Container db-1   Started\r\n"]

Each event is a tuple: [timestamp_seconds, event_type, data]

• "o" — output (text written to terminal)
• "i" — input (keystrokes, if recorded)

Parse the cast file to extract the exact commands run, their output, and timing information. The env header tells you the shell and terminal type.

Transcripts

For simpler use cases, the transcript endpoint returns plain text with ANSI codes stripped:

GET /api/v1/gifs/{id}/transcript/

Response:

$ docker compose up -d
Creating network...
Container app-1  Started
Container db-1   Started

Transcripts are ideal for search indexing, embedding in LLM context windows, and quick content extraction.

Structured JSON API

The REST API returns full metadata for every GIF:

GET /api/v1/gifs/{id}/

This includes title, command, tags, shell, theme, file dimensions, embed codes, and download URLs — everything an agent needs to understand and reference the GIF. See the full API reference.

For bulk operations, use the list and search endpoints:

# Find all GIFs about Docker
GET /api/v1/search/?q=docker

# Browse by tag
GET /api/v1/tags/kubernetes/gifs/

# Featured GIFs (curated quality)
GET /api/v1/featured/

llms.txt

The /llms.txt file provides a site-level summary optimized for AI crawlers. It describes what AgentGIF is, lists all API endpoints, and explains how to discover and consume content.

This follows the llms.txt convention — a lightweight alternative to sitemaps for AI agents that want to understand a site's structure quickly.

Discovery & Crawling

AI agents can discover GIFs through multiple channels:

The robots.txt allows all crawlers — AgentGIF welcomes AI agents.

Use Cases for AI Agents

Documentation Generation

An AI agent can search for GIFs by tool name, retrieve the cast file, and automatically generate documentation with embedded demos:

# Find a demo for "git rebase"
curl -s "https://agentgif.com/api/v1/search/?q=git+rebase" | jq '.results[0]'

# Get the cast file for step-by-step extraction
curl -s "https://agentgif.com/api/v1/gifs/xK9mQ2pL/cast/"

Tutorial Assembly

Agents can browse collections of related GIFs and assemble step-by-step tutorials with the correct ordering and context.

Code Review Assistance

When a PR includes a GIF demo, an AI agent can fetch the cast file, parse the commands, and verify they match the PR description.

CLI Tool Discovery

The tools directory catalogs CLI tools with associated GIF demos. Agents can browse tools by category and find real-world usage examples.