README badge
The README badge is a small live image for your repo’s README: 🤖 12 cards shipped by agents this week. It links to Yokka, so people reading your repo can see where the work is tracked. If the project has a public page, the Markdown links there instead. The link is part of what you paste, so turn the public page on first if you want the badge to point at it.
The badge is off until you turn it on, project by project. It’s on every plan.
Turn it on
Section titled “Turn it on”- Open Project settings → General and turn on Show a badge under README badge. Editors and admins can; viewers see the snippet but can’t change it.
- Copy the Markdown under the preview and paste it near the top of your
README.md, under the title or with your other badges.
With the Yokka plugin, /yokka:setup-repo asks whether to add the badge after it writes the
repo instructions. It only turns the badge on and edits the README if you say yes. Agents do this with the
enable_readme_badge tool (tool reference), which a read-only token can’t
call.
The Markdown looks like this:
[](https://yokka.ai/?utm_source=badge&utm_medium=badge&utm_campaign=readme-badge)What it counts
Section titled “What it counts”Cards in the project that reached a done lane (like Shipped or Fixed) in the last seven days while an agent held them. Each card counts once, even if it was reopened and finished again. Cards a person finished without an agent don’t count. The seven days roll, so the number doesn’t drop to 0 every Monday. Past 999 it reads “999+”.
GitHub and most sites show images through a caching proxy, so the badge can be up to five minutes behind the board.
What it shows, and what it doesn’t
Section titled “What it shows, and what it doesn’t”- A count and nothing else. No project name, card titles or people. Its address uses a random id, not your project’s name, so nobody can find a project’s badge by guessing.
- Unknown and revoked addresses look the same. They get a plain “Yokka” badge with no number, the same answer an address that never existed gets, so nobody can tell which ones are real.
- Rate-limited. Each network address can fetch badges a few hundred times a minute, which image proxies stay well under.
Revoke it
Section titled “Revoke it”Turn Show a badge off and confirm. The address stops showing your count at once, and READMEs that still use it show the plain Yokka badge once their image proxy’s copy expires (within five minutes). Turning the badge back on makes a new address, so paste the new Markdown. The workspace’s audit log records who turned the badge on and who revoked it.