TL;DR: GitHub renders any URL ending in .gif inline with  — no plugins, no player. The friction is producing the GIF: recording it, converting it, shrinking it under GitHub's 10MB limit, and hosting it. You can skip all of that with screencli — one command drives a browser, records the flow, and exports a README-ready GIF with --preset github-gif. Place it in the first screenful, keep it under 5MB, and you're done.
Why your README needs a demo GIF
A demo GIF is the highest-leverage change most READMEs can make. It converts a skim into a click faster than any paragraph.
The evidence is blunt. A developer who analyzed 116 top-starred open-source READMEs (posted to r/SideProject in 2026) found that adding a single demo GIF moved a project's "visual proof" score from 18 to 62 out of 100 — the biggest single jump of any change they tested. GitHub's own research, cited in the popular "README that gets stars" template guides of 2026, shows repos with detailed READMEs get roughly 50% more contributions than bare ones.
Most developers decide whether to star a repo within the first 15 seconds. For CLI tools especially, a short terminal or browser GIF is proof — text can claim something is fast or simple; a GIF shows it.
The rule every top repo follows: show the product in the first screenful, right after the one-line description.
The old way is tedious
Here's the workflow the top-ranking guides still recommend in 2026, and why almost nobody keeps their GIFs up to date:
- Open a screen recorder (QuickTime, GIPHY Capture, ShareX) and capture the flow.
- Re-record because you clicked the wrong thing or the timing was off.
- Trim the dead space in a separate editor.
- Convert the MP4 to a GIF (ezgif, veed.io, or
ffmpeg). - Shrink it under GitHub's limit with
gifsicle— reduce colors, drop the frame rate. - Host it, either by committing it to an
/assetsfolder or a dedicatedmediabranch.
That's four or five tools for a 15-second clip. It's why README GIFs go stale the moment the UI or CLI output changes — nobody wants to run the gauntlet twice.
How GitHub actually renders GIFs
GitHub renders animated GIFs natively — no video player, no extension, no configuration. Any URL ending in .gif embedded with standard markdown image syntax auto-plays when the page loads.
Standard markdown:
Use an HTML <img> tag when you need to control the display width:
<img src="./assets/demo.gif" alt="Demo of the CLI recording a browser session" width="700" />
The catch is file size. According to GitHub's documentation on attaching files, the maximum size for an image or GIF uploaded via drag-and-drop to an issue, PR, or comment is 10MB (25MB for other file types). For GIFs committed directly into a repo there's no hard block, but large committed files slow down git clone for everyone. Practical targets: under 5MB for fast loading, and under 3MB for repos that get cloned often.
There's also a hosting trick worth knowing. To keep a large GIF out of your repo history entirely:
- Open any issue in your repository (a throwaway is fine).
- Drag the GIF into the comment box — do not submit the issue.
- GitHub uploads it to its CDN and inserts a
https://github.com/<user>/<repo>/assets/...URL. - Copy that URL and use it in your README.
The file lives on GitHub's CDN, not in your clone.
The fast way: generate the GIF with screencli
screencli is an AI-powered screen-recording CLI. Instead of driving the recorder yourself, you describe the demo and an agent performs it in a real browser, then exports a polished, README-ready GIF — no editor, no converter, no gifsicle.
Step 1 — record the flow:
npx screencli record https://your-app.com -p "Open the dashboard, create a new project, and show the success toast"The agent follows your prompt, and screencli records with auto-zoom, click highlights, and a cursor trail.
Step 2 — export a README-ready GIF:
npx screencli export ./recordings/a3f2c8e1 --preset github-gifThe github-gif preset outputs an 800×450 GIF sized for a README or PR — already optimized to sit comfortably under GitHub's 10MB limit.
Step 3 — embed it. Commit the GIF to your repo's /assets folder (or use the CDN trick above) and drop it into the first screenful:
<p align="center">
<img src="./assets/demo.gif" alt="screencli recording a browser demo" width="700" />
</p>
When your UI changes, re-run the same two commands — the whole loop is under two minutes instead of a multi-tool afternoon. Sign in with GitHub on first run and you get 15 free credits per month.
Try it now → npx screencli record https://your-app.com -p "your demo prompt"
Best-practice settings for README GIFs
Commonly recommended targets for a clean, fast-loading README demo:
| Parameter | Recommended | Maximum |
|---|---|---|
| Width | 600–800 px | 1200 px |
| Frame rate | 10–15 fps | 30 fps |
| Duration | 5–15 s | 30 s |
| File size | 1–5 MB | 10 MB |
Beyond the numbers: write descriptive alt text (it doubles as accessibility and SEO), place the GIF within the first screenful, and skip a heading directly above it so the README stays clean while the GIF loads.
How the approaches compare
| Approach | Tools involved | Time per GIF | Editing | Hosting |
|---|---|---|---|---|
| QuickTime + ffmpeg + gifsicle | 3–4 | 30–60 min | Manual trim + optimize | Manual |
| GIPHY Capture → ezgif | 2 | 15–30 min | In-browser trim | Manual |
| asciinema / VHS (terminal only) | 1 | 10–20 min | Config file | Manual |
| screencli | 1 | 1–2 min | None (auto) | Repo or CDN |
asciinema and VHS are excellent for pure terminal casts, but they can't record a browser flow. screencli covers both real browser demos and CLI walkthroughs, and handles the post-production — zoom, highlights, sizing — for you.
FAQ
Does GitHub support GIFs in a README by default?
Yes. GitHub renders any .gif URL embedded with  automatically — no plugins or configuration. The GIF plays on page load.
What's the file size limit for a README GIF? Per GitHub's docs, drag-and-drop uploads to issues, PRs, and comments cap at 10MB for images and GIFs. Aim for under 5MB regardless, so the README loads fast for everyone.
Can I add a GIF without committing it to my repo?
Yes. Drag it into an issue comment (don't submit), copy the github.com/<user>/<repo>/assets/... URL GitHub generates, and reference that in your README. The file stays on GitHub's CDN, out of your clone history.
Can I record a demo behind a login?
Yes. screencli's --login --auth <name> flags let you log in manually first, then hand off to the agent — your login is never recorded, and the saved session is reused on the next run.
How do I keep the GIF from going stale? Automate it. Because screencli is a single command, re-recording after a UI change takes under two minutes — cheap enough to redo every release instead of letting the demo drift out of date.
Run it yourself → npx screencli export ./recordings/<id> --preset github-gif