What is a costly signal in the context of an open source project?

A costly signal is any observable thing about your repository that would have been expensive or impossible to produce if the project were not genuinely maintained — passing CI, recent commits, real documentation, answered issues, a working demo video. The cost is what makes it believable, because a low-effort project cannot cheaply imitate it. Claims that cost nothing to write, like calling your project production-ready, are what economists call cheap talk and carry almost no weight with experienced developers.

Does a demo video actually help an open source project get adopted?

It helps for two reasons. The direct one is comprehension: a first-time visitor decides in well under a minute whether to keep going, and a short demo answers what your project does faster than any paragraph. The indirect one is inference — a video cannot exist unless the project runs, and making one signals that someone intends to keep maintaining it. That second effect is why a video often out-performs a longer, better-written README, and why it belongs above the fold rather than at the bottom.

If AI can generate the video, is it still a costly signal?

Partly, and honestly less than it was. Signaling theory predicts that when a signal gets cheap to produce, it stops separating good projects from bad ones — which is exactly what happened to automated directory listings. What still carries information is the judgment that does not automate (choosing what to show, checking it is accurate, keeping it current) and the simple fact that most repositories still have no video at all. The gap is real today and will narrow, which argues for adding one sooner rather than later.

Where should the video go so that it actually functions as a signal?

Above the fold in your README, immediately after your one-sentence description, so it reaches every first-time visitor rather than only the ones who scroll. GitHub does not render inline video tags, so the standard approach is a clickable thumbnail image or an animated GIF linking to the hosted clip. Reuse the same video on your launch posts, your Product Hunt page, and your project site — one video, embedded once and shared everywhere, keeps sending the signal long after launch week.

Why a Demo Video Is a Costly Signal for Your Open Source Project

Nobody Can Judge Your Code From the Outside

A developer landing on your repository for the first time wants to answer one question: is this worth my time? They cannot answer it by reading your source, because reading enough source to judge a project properly costs more than simply trying the next alternative. So they decide on proxies — the README, the commit history, the star count, whether anything on the page looks maintained — and they do it in well under a minute. Economists have a name for this situation: information asymmetry. You know whether your project is solid; the visitor does not, and has no cheap way to find out. Every decision they make about you is made from the outside, using signals. Understanding which signals actually carry information is the difference between a repo that converts visitors and one that gets a polite star and no return visit.

Why Your Own Claims Do Not Count

The instinct is to answer the trust problem with words: production-ready, battle-tested, blazingly fast, used in production by teams worldwide. The problem is that these cost nothing to type. A maintainer with a robust, well-tested project and a maintainer with a weekend prototype can write the identical sentence in the identical amount of time. Because the claim is equally available to both, it cannot separate them — and an experienced developer, who has been burned before, discounts it to roughly zero. Economists call this cheap talk: communication that is free to produce and therefore carries no information, no matter how true it happens to be in your particular case. This is why feature lists in a README persuade so much less than maintainers expect. It is not that the features are uninteresting. It is that anyone could have written them.

Stop reading, start shipping. RepoClip turns your GitHub repo into a narrated demo video in minutes — no editing required.

The Handicap Principle: Cost Is What Makes a Signal Honest

In 1975 the biologist Amotz Zahavi published an answer to a long-standing puzzle: why do peacocks grow tails that slow them down and make them conspicuous to predators? His proposal, the handicap principle, was that the handicap is the message. Any bird can be born; only a genuinely fit one can afford to drag an enormous tail around and survive anyway. The cost is not a side effect of the signal — the cost is what makes it impossible to fake. Two years earlier, the economist Michael Spence had arrived at the same structure from a completely different direction, arguing in his job-market signaling work that a degree communicates ability precisely because it is cheaper to obtain if you are capable. He later shared a Nobel Prize for it. The rule that falls out of both is short: a signal is credible in proportion to what it costs the sender.

How Signaling Theory Reached Marketing

The idea moved into marketing quickly. Phillip Nelson argued in 1974 that advertising informs buyers even when the advertisement itself says nothing of substance. Paul Milgrom and John Roberts formalised that in 1986, showing that introductory pricing and deliberately uninformative advertising spend can both function as credible quality signals, because only a firm that expects customers to come back can afford to burn the money up front. Amna Kirmani and Akshay Rao gave the field its standard review in 2000 under a title that is the whole thesis in three words: No Pain, No Gain. Their point was not that expensive marketing is good marketing. It was that the observable expense is the part carrying the information — and that a marketing move which costs nothing communicates nothing, however well-crafted it is.

The Signals Developers Already Read on a Repository

Apply the cost test to the things a developer scans on a repo and they sort themselves immediately. A green CI badge costs a working test suite that you keep passing. Recent commit activity costs sustained attention over months. Substantial documentation costs hours that produce no new features. A responsive issue tracker costs the maintainer's evenings. These are all expensive, which is exactly why they persuade. At the other end sit the things that cost nothing: adjectives in the description, a badge wall that reports nothing meaningful, a star count that could have come from anywhere, a roadmap of features that do not exist yet. Developers have learned to weight the first group and ignore the second, usually without being able to articulate why. They are running Zahavi's test without knowing its name.

Why a Demo Video Sits at the Top of That List

A demo video is unusual because it is costly in several directions at once. It cannot exist unless the project actually runs, which rules out the vaporware case entirely. It requires you to decide what your project is for and say it out loud in a sentence, which is harder than listing features and much harder to fake. And historically it required real production effort — scripting, recording, editing — which most maintainers simply never spent. That last part is what made it such a strong signal: the video's content mattered less than the fact that someone had bothered to make one at all. A visitor seeing a demo at the top of a README draws an inference that no adjective can produce, which is that this project has an owner who intends to be around. That inference, not the sixty seconds of footage, is what converts.

Does AI Make the Signal Cheap Again?

This is the honest objection, and the theory answers it rather than dodging it: yes, partly. When the cost of producing any signal collapses, its informational value collapses with it. That is precisely what happened to directory listings and automated backlinks, which were briefly persuasive and are now noise. If every repository on GitHub carried an auto-generated video tomorrow, having one would stop distinguishing anybody. Two things survive that compression. The first is the cost that does not automate: deciding what to show, judging whether the result is accurate, and keeping it current as the project changes — the same reason a generated README still needs an editor. The second is relative, and it is where the value sits today: signal strength depends on being distinguishable from the people who did not bother, and the overwhelming majority of repositories still have no video at all. That gap is real now and will narrow later, which is an argument for sending the signal early rather than an argument against sending it.

What Makes a Video Read as Costly — or as Cheap

Because the inference is about effort, the details that betray a lack of it do disproportionate damage. Generic stock imagery that could belong to any product says nobody chose it. Narration that reads your feature list aloud says nobody thought about the audience. A three-minute runtime says nobody edited. And a watermark from a free tier says, unavoidably, that the maintainer would not spend on their own project — which is exactly the inference you were trying to prevent. The reverse also holds: a tight sixty seconds that opens on the problem, shows the result before explaining the mechanism, and ends with one clear next step reads as deliberate, because it is. Our guide to product demo video best practices covers the structure in detail, and how to create a demo video for your GitHub project compares the routes to producing one.

Cheap Distribution Fails the Same Test

The framework generalises past the repo page. Submitting your project to a hundred tool directories takes an afternoon and takes an afternoon to fake, so the resulting links persuade nobody and, in practice, mostly attract automated traffic — we read a full day of our own raw analytics and found that the overwhelming majority of those referral sessions were not people. Meanwhile the channels that require something expensive of you — writing something worth ranking for, earning a place in a curated list that reviews submissions, sustained participation in a community before you post your own work — deliver far fewer visitors and far better ones. This is the same lesson as the indie distribution paradox, viewed through cost rather than effort, and it is why the promotion channels that actually work are the slow ones.

Send the Signal Before You Need It

The practical conclusion is unglamorous. Put a demo video above the fold in your README, where it does its work on every first-time visitor rather than only on launch day — GitHub strips inline video tags, so use a thumbnail or GIF that links to the full clip. Keep it current, because a demo showing a version two releases old signals neglect just as loudly as a fresh one signals care. Producing that video used to cost a weekend, which is why so few maintainers ever did it; tools like RepoClip now generate a narrated demo from a repository URL in minutes, which removes the excuse without removing the inference, since the visitor still sees a project whose owner bothered. The signal is worth most while it is still scarce. That is now.