AI Agent-Readable GIFs — Machine Layer Documentation

Le problème

Les images GIF sont opaques pour les agents IA. Quand un README contient un GIF de démo terminal, un agent IA voit des données binaires de pixels — il ne peut pas extraire les commandes, comprendre la sortie ni référencer des étapes précises. C'est une limitation fondamentale de la documentation basée sur les images.

AgentGIF résout ce problème en associant des données structurées lisibles par machine à chaque GIF.

Architecture double couche

Chaque GIF sur AgentGIF possède deux couches qui coexistent à la même URL :

Un humain voit un terminal animé. Un agent IA voit des données structurées : commandes, sortie, horodatages, métadonnées et codes d'intégration.

Fichiers Cast (Asciinema v2)

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

Accéder au Cast

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

Structure du fichier Cast

La ligne 1 est un en-tête JSON avec les métadonnées terminal :

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

Les lignes suivantes sont des tuples d'événements :

[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"]

Chaque tuple est [timestamp_seconds, event_type, data] :

• "o" — output event (text written to the terminal screen)
• "i" — input event (user keystrokes, if captured)
• Les horodatages sont en secondes depuis le début de l'enregistrement
• Les données peuvent contenir des codes d'échappement ANSI pour les couleurs

Analyser un fichier Cast

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("$ ")]

Transcriptions

Pour les cas d'utilisation plus simples, le point d'accès de transcription renvoie du texte brut propre :

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

Les transcriptions suppriment les codes d'échappement ANSI, condensent les espaces blancs et présentent la session terminal comme un texte lisible. Elles sont idéales pour :

• Intégration dans les fenêtres de contexte LLM (jetons minimaux)
• Indexation de la recherche plein texte
• Génération de documentation à partir de sessions enregistrées
• Comparaison de la sortie terminal entre les GIF

Points d'accès .md

Chaque page d'AgentGIF possède une variante Markdown. Ajoutez .md à n'importe quelle 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

La réponse est text/markdown; charset=utf-8 — texte propre et structuré que les LLM peuvent analyser directement.

API JSON

L'API REST fournit des données structurées complètes. Aucune authentification nécessaire pour les lectures :

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

Découverte de contenu

Les agents IA peuvent découvrir le contenu AgentGIF via plusieurs canaux :

Exemples concrets

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