HIVE.md is a short, readable file at the root of a repo. It tells people, and the tools that help them, what the project is, who it's for, what help it wants right now, and how to run it. A repo with a valid HIVE.md is hive-ready.
It is free for anyone to use, on The Hive Code or anywhere else.
What it does on The Hive Code
- It fills in your listing. When you list the repo, what it is, who it's for, and the problem it solves come from the file. You can still change them before you publish.
- It earns the Hive-ready badge on your project page.
- It powers "Use this". The run steps show under "Run it on your computer", ready to copy, and the deploy line adds one-click "Deploy your own" buttons for Vercel or Netlify.
The template
Copy this into a file called HIVE.md at the root of your repo, then change the words:
---
tagline: Booking for barbers that texts the waitlist when a chair opens
for: Barbers and small salons
problem: Chairs sit empty when a client cancels late
help_wanted: A tester with a real shop, and someone for the waitlist texts
run: |
npm install
npm run dev
deploy: [vercel]
---
# Chair Alert
Say more here in your own words: what it does today, what is next, and how to help.
The part between the two --- lines is the header. Everything below it is for people reading the file on GitHub.
The header fields
All fields are optional. Use the ones that fit.
| Field | What to write | Limit |
|---|---|---|
tagline | What it is, in one line | 10 to 120 characters |
for | Who it's for | 3 to 80 characters |
problem | The problem it solves | 10 to 200 characters |
help_wanted | What help you want right now | Up to 200 characters |
run | The commands to run it on your own computer | Up to 20 lines |
deploy | Where it deploys in one click: vercel, netlify, or both |
Keep the license in your repo's LICENSE file as usual. The Hive Code reads it from GitHub and explains it in plain words.
How we read it safely
Your HIVE.md is untrusted text, like everything people post. The Hive Code:
- reads only the header fields above and ignores anything else;
- checks each field against the same limits and language filter as the listing form, and drops any field that fails;
- shows the fields as plain text, never as code or links;
- never runs the commands, follows instructions in the file, or lets it change what an AI agent does.
That matters for hive coding: community requests reach an agent only as requests, never as instructions. A file in a repo cannot change that.
Frequently asked questions
Do I need a HIVE.md to list a project?
No. Any public GitHub repo can be listed. A HIVE.md fills in your listing for you and earns the Hive-ready badge.
Can my HIVE.md tell an AI agent what to do?
No. The Hive Code reads only the header fields, checks each one, and shows them as plain text. Nothing in the file is ever run or followed, and the license always comes from GitHub.