Your README already contains the script. Here's the approach that turns it into a watchable 60-second demo from editable scenes — and the place it quietly falls apart.
Your README already contains the script. The install command, the quickstart, the one API call that shows what the project does — that's the outline of a good 60-second demo. The hard part was never the words. It was turning them into something watchable without booking an editor or fighting a timeline for an afternoon.
Here's the approach that works, and the place it quietly falls apart.
Why the README is the right source
Most “make a video from text” tools start from a blank prompt, so you get generic filler — a smooth voice saying nothing your project actually does. A README is the opposite: it's specific. It names the real command, the real flag, the real function. If you ground the script in it, the video says what the repo says, not what a model guessed.
That grounding is the whole trick. Point the generator at the README (or paste it in), and the script should come back with your actual install command, your actual import, your actual quickstart — not “simply install the dependencies and get started in seconds.” When it drifts into that kind of language, that's your signal the grounding isn't working and you're back to filler.
The shape of a good repo demo
Sixty seconds, roughly four beats:
- The problem, in one line. What does this exist to fix? The README's first paragraph usually already says it.
- Install. One command, shown as a terminal that types itself out.
- The one thing it does. The quickstart — the smallest example that proves the point — as a syntax-highlighted code card, not a screen recording of your editor.
- Where to go next. Docs link, GitHub stars, the install command again. Two seconds, then out.
The reason to render these as components rather than screen-record them is boring but important: a screen recording of a terminal is unreadable on a phone, and it's frozen the moment your CLI changes. A typed-out terminal component and a code card are legible at 9:16 and editable after the fact.
A worked example: a CLI in four beats
Take a concrete shape: a command-line tool that tails logs from several servers at once. Its README has an install line, a quickstart, and a GIF nobody can read on a phone. The four beats become:
- Hook: “You're still SSHing into three boxes to read one request's logs.” The problem line, addressed to the viewer, lifted almost verbatim from the README's first paragraph.
- Install: the one npm command as a terminal scene that types itself, holds on the success line for a beat, and moves on. Four seconds.
- The one thing: the quickstart command, then the payoff — merged, colorized output — as a second terminal beat. If your payoff is config or code rather than output, it's a code card instead.
- Out: “Docs and repo below.” The install command on screen one more time, then end. No outro music, no subscribe animation.
Notice what isn't in it: your face, a screen recording, an intro. A README demo is a proof, not a vlog. The fastest version that shows the thing working beats the polished version that shows you. If you catch yourself planning a thumbnail before you've proven the quickstart on screen, you're making the wrong video first.
The hook is the only genuinely hard part
Everything else in the four beats is transcription — the README already wrote it. The hook is the one line the README doesn't contain, because READMEs open with what a project is, and a Short has to open with why anyone should care. The patterns that work for dev tools are unglamorous: the problem stated as something the viewer is doing right now (“you're still…”), a before/after (“this deploy took 40 minutes; this one takes 2”), or a specific number that raises a question. The pattern that fails is the feature list — “X is a fast, lightweight, extensible…” — because it answers a question nobody asked yet.
Spend your editing time there. If you rewrite one thing the generator drafted, rewrite the first line. A decent mechanical check: read the hook alone, with no context — if it doesn't raise a question a stranger would want answered, it's a description, not a hook.
Grounding, mechanically
In ReelMint the grounding isn't a vibe, it's a step. Connect the repo's docs — or paste the README — as a knowledge-base source, and script generation searches it before writing a line, so the draft quotes your actual command instead of inventing one. A script check runs before anything renders: hook strength, duration against your target, phrasing your narrator will trip on. And any scene can be previewed as a three-frame film strip — start, middle, end — in seconds, so you catch the wrong flag while it's still text.
None of that requires an agent — it's the same pipeline from the web editor. But if you live in a terminal anyway, the whole loop is driveable from Claude Code over MCP: point it at the repo, ask for the four-beat draft, and review the scenes it proposes.
The part that saves you later
Here's the difference that matters six weeks from now, when you rename a flag or bump a version. If the demo was a recording, it's stale and you re-record. If it was built from editable scenes, you open the one scene with the old command, fix the text, and re-render. The video tracks the repo instead of rotting away from it.
That's also why “one afternoon” collapses to “about an hour — ten to twenty minutes of it yours.” You're not performing a take; you're reviewing a document that happens to render as video.
Keeping it alive after you ship
Publish is where a repo demo usually dies: it goes on the channel, the repo moves on, the video rots. Two mechanics change that. Re-publishing an updated render replaces the existing YouTube video instead of uploading a duplicate — so the link in your README and the view count both survive the fix. And because the scenes hold text, “update the demo for v2” is a diff-sized edit, not a production.
If the project ships on a cadence, the video can too: a Short per release, drafted from the changelog, is exactly the dull, regular work worth handing to an agent — with you approving each draft before it goes anywhere. Releases become a series rather than one orphaned demo, and the channel compounds the same way the repo does: one small, correct addition at a time.
Where it honestly falls apart
Two failure modes, stated plainly.
The first: a thin README makes a thin video. If your README is three sentences and a badge, there's nothing to ground a script in, and no tool fixes that — you'll get something generic because the source was generic. Write the README first; the video is downstream of it.
The second: the demo is not a substitute for the real thing. A code card is the right way to show an API call, but if your project's whole value is an interactive UI, a component-built explainer only takes you so far — at some point you want a real screen recording of the actual product, and that's a different tool. Be honest with yourself about which kind of project you have.
This space is also getting crowded fast — there are now several tools that read a repo and spit out a video (a couple are genuinely good). The differentiator worth caring about isn't “can it generate a video,” it's “can I edit the fourth scene without redoing the other three.” That's the question to ask any of them.
Why sixty seconds, and why vertical
Because that's where the audience is that hasn't already starred your repo. A landing-page video reaches people who found you; a Short reaches people who didn't — Shorts and Reels are recommendation surfaces, and a sharp problem-line hook is exactly the kind of thing they test in front of strangers. The format constraints are real, though: 9:16 means a terminal can show one command legibly, not a tmux session; sixty seconds means one idea, proven once. Treat the constraints as an editor. If your demo doesn't fit, that's usually the demo trying to be a tutorial — make the tutorial too, separately, and let the Short do the one job of making someone curious.
And once it exists, spend it: embed it on the repo page, link it from the release notes, put it in the docs' getting-started. The same sixty seconds that works as a Short is the best above-the-fold answer to “what is this project?” you'll ever ship.
Doing it
If you want to try the editable-scenes version: point the studio at your README, let it draft the four-beat script, then open each scene and make it true — fix the command, swap the snippet, tighten the hook. Render when it's right, publish to your channel. The README did most of the work; you're just making sure the video didn't round off the details that make your project yours.
Originally published on reelmint.io.
Top comments (0)