The constraint: autoplay, no controls, impatient readers
A GIF in a README starts playing the moment the page renders and loops until the tab dies. Nobody can pause it, scrub it, or slow it down, because GitHub gives GIFs no player chrome at all. That's a gift and a trap. The gift: your demo runs without asking anyone to click. The trap: a visitor deciding whether to clone your repo gives the animation a second or two, so if the loop opens with you hunting for the right menu, that's the demo they judge.
GIF is also a spectacularly inefficient container. Every frame is stored more or less whole, the palette tops out at 256 colors, and there's no motion compression worth the name. Left unattended, a twenty-second capture of a full desktop lands in the tens of megabytes. The work is deciding what not to ship: fewer seconds, fewer pixels, fewer colors, chosen deliberately.
GitHub's actual numbers
Two caps matter. Upload through the web interface and GitHub rejects anything over 25 MB. Push through git and files past 100 MB draw warnings or refusals. Neither is a budget, though. The budget is what a stranger on a phone will tolerate, and that puts a good README GIF between 2 and 8 MB. Over that, mobile readers watch a gray box slowly resolve while your first impression evaporates.
Hosting is a fork in the road. Commit the file to the repo (a docs/ or assets/ folder is the convention) and reference it by relative path; it stays versioned and shows up in offline clones. Or drag it into an issue or the README editor, let GitHub park it on the user-content CDN, and paste the URL it hands back; your repo stays lean. Both routes work. Both reward a file that was small before it ever left your machine.
Capture the demo, convert it locally
Grab the footage with whatever recorder you already trust: Cmd+Shift+5 on macOS, the Game Bar on Windows, OBS on Linux. Save an MP4 or MOV and drag it into the converter. From there every step runs as client-side code on your own hardware. No upload progress bar, no queue, and no copy of your staging environment or half-built feature resting on someone else's server. Longer captures from meetings or full work sessions follow the same path; the screen recording guide walks that case.
Settings that keep terminal text readable
Small file and legible text pull in opposite directions. These are the levers, roughly in order of payoff:
- Trim to the payoff. Start the clip on the frame the command fires and end it just after the output settles. Four to six seconds is the zone where a loop still feels like a loop. The timeline resolves to individual frames, and the arrow keys inch a cut point across them, so the loop opens precisely where you decide.
- Hold 10 to 15 fps. A scrolling terminal or a button click reads fine at 10. That alone roughly halves the file against a 24 fps export, and only smooth cursor travel justifies the top of the range.
- Downscale to display width. The README column renders around 900 px on desktop and far less on phones, so exporting at 800 px wide (narrower for a terminal pane) costs nothing visible. Dimensions move file size more than any other control here.
- Start the palette low. A dark terminal theme often survives 64 colors untouched; step up toward 128 if the syntax highlighting starts to band. Dithering smooths gradients at the cost of some bytes, so toggle it and compare both versions.
- Crop the dead space. Lock 16:9 around an app window or 1:1 around a terminal pane and drop the menu bar, the dock, and the wallpaper. Every cropped pixel is one you stop paying for on every single frame.
A running estimate of the output size sits alongside the controls and updates with every change, so getting under 8 MB is a decision, not a surprise. If the target is smaller still, the small-file recipe pushes the same levers harder.
The Markdown, and where the GIF goes
Embedding is one line, the same syntax as any image:
- Committed to the repo: 
- Hosted by GitHub: 
- Clickable, pointing at docs or a full video: [](https://your-docs-link)
Place it directly under the title and one-line description so it sits above the fold, and write real alt text inside the brackets, both for screen readers and for the day the image fails to load. After that, the file is portable: the same loop can front a product demo on a landing page or a changelog entry without another export.