AI Agent-Readable GIFs — Machine Layer Documentation

How AI agents read terminal GIFs through cast files, transcripts, .md endpoints, and structured APIs.

समस्या

GIF चित्र AI एजेंटों के लिए अपारदर्शी हैं। जब README में terminal demo GIF होता है, तो एक AI एजेंट बाइनरी पिक्सेल डेटा देखता है — वह कमांड निकाल नहीं सकता, आउटपुट समझ नहीं सकता, या विशिष्ट चरणों का संदर्भ नहीं दे सकता। यह छवि-आधारित दस्तावेज़ीकरण की एक मूलभूत सीमा है।

AgentGIF इसे प्रत्येक GIF में संरचित, मशीन-पठनीय डेटा जोड़कर हल करता है।

दोहरी परत वास्तुकला

AgentGIF पर प्रत्येक GIF में दो परतें हैं जो एक ही URL पर सह-अस्तित्व में हैं:

परत	उपभोक्ता	प्रारूप	पहुंच
दृश्य	इंसान	GIF / MP4	`media.agentgif.com/{id}.gif`
मशीन	AI एजेंट	Cast / Transcript / JSON / Markdown	API endpoints + .md प्रत्यय

एक इंसान एनिमेटेड terminal देखता है। एक AI एजेंट संरचित डेटा देखता है: कमांड, आउटपुट, timestamp, मेटाडेटा और embed कोड।

Cast फ़ाइलें (Asciinema v2)

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

Cast तक पहुंच

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

Cast फ़ाइल संरचना

पंक्ति 1 terminal मेटाडेटा के साथ एक JSON header है:

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

बाद की पंक्तियां 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"]

प्रत्येक tuple [timestamp_seconds, event_type, data] है:

"o" — output event (text written to the terminal screen)
"i" — input event (user keystrokes, if captured)
Timestamp रिकॉर्डिंग शुरू से सेकंड में हैं
डेटा में रंगों के लिए ANSI escape कोड हो सकते हैं

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

Transcript

सरल उपयोग के मामलों के लिए, transcript endpoint स्वच्छ सादा पाठ लौटाता है:

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

Transcript ANSI escape कोड हटाते हैं, whitespace संक्षिप्त करते हैं और terminal session को पठनीय पाठ के रूप में प्रस्तुत करते हैं। वे इनके लिए आदर्श हैं:

LLM context windows में embed करना (न्यूनतम token)
फुल-टेक्स्ट खोज अनुक्रमण
रिकॉर्ड किए गए session से दस्तावेज़ीकरण बनाना
GIF में terminal आउटपुट की तुलना करना

.md Endpoints

AgentGIF का प्रत्येक पेज Markdown संस्करण रखता है। किसी भी URL में .md जोड़ें:

# 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

प्रतिक्रिया text/markdown; charset=utf-8 है — स्वच्छ, संरचित पाठ जिसे LLM सीधे पार्स कर सकते हैं।

JSON API

REST API पूर्ण संरचित डेटा प्रदान करता है। पढ़ने के लिए कोई प्रमाणीकरण आवश्यक नहीं:

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

सामग्री खोज

AI एजेंट कई चैनलों के माध्यम से AgentGIF सामग्री खोज सकते हैं:

चैनल	URL	के लिए सर्वश्रेष्ठ
llms.txt	`/llms.txt`	साइट संरचना समझना
XML Sitemap	`/sitemap.xml`	सभी पेज क्रॉल करना
RSS/Atom	`/feed/`, `/feed/atom/`	नए GIF ट्रैक करना
खोज API	`/api/v1/search/?q=...`	विशिष्ट सामग्री खोजना
टैग सूची	`/api/v1/tags/`	श्रेणी द्वारा ब्राउज़ करना
टूल इंडेक्स	`/tools/`	CLI टूल द्वारा ब्राउज़ करना
OpenAPI spec	`/api/openapi.json`	API schema समझना

वास्तविक दुनिया के उदाहरण

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

← सभी गाइड · Agent एकीकरण Docs →