How I spent a day automating something that takes 10 seconds to do manually, and why you should absolutely use it.
Let me paint you a picture.
You're a developer. You open a developer's GitHub profile. There's a nice README: some skills, a few projects, maybe a visitor counter they definitely copied from Stack Overflow.
Then you see it.
"Won as Black against a 1542-rated opponent. Sicilian Defense. 38 moves. Currently on a 5-game win streak."
You don't even play chess. You have no idea what any of that means. But you understand one thing. This person has a personality besides coding. This person ships things. This person spent their weekend building an automated README updater instead of touching grass.
Here's why you need a chess stats card on your GitHub profile
You don't.
Let's be honest; you absolutely do not need this. Your README was fine. Your projects speak for themselves. Nobody hiring you as a backend engineer cares that you blundered a rook on move 23.
But here's the thing about developer profiles in 2026: everyone has the same README. Skills section. Projects section. GitHub stats card showing 847 contributions in green squares. A wavy SVG banner someone generated at readme.so.
Chess stats? Nobody has that. And the ones who do are immediately more interesting than the ones who don't.
That's the whole pitch. That's the blog post.
Lemme tell you more about it since you seem interested.
The origin story (it's embarrassing)
I was procrastinating.
I had actual work to do real features, real projects. Instead I was playing Blitz on Chess.com at 1am, losing to some 500 rated, and thinking: "I wish my GitHub profile knew about this loss so it could share in my suffering."
That thought, which a normal person would have dismissed immediately, lodged itself in my brain.
By 2am I had an API route. By 3am I had a GitHub Action. By 4am I had deployed it to Vercel, watched it fail, fixed the UTF-8 encoding issue that was turning chess pieces into hieroglyphics, and gone to sleep feeling like I had accomplished something meaningful.
I had not accomplished something meaningful. But I had built something cool.
What I actually built
chess-readme-stats does two things:
Story mode — a narrative text block that lives in your README and auto-updates every 6 hours via GitHub Actions. It reads your Chess.com games, figures out what happened, and writes a little story about it.
It looks like this:
2026-06-10 · Blitz (3 min) · Playing as White
Opponent resigned after 38 moves
Opening: Sicilian Defense · ECO B20
Accuracy: 91.2%
Opponent: johndoe · 1542 rated (55 points above you)
Rating: 1487 → 1495 (+8)
Streak: 5-game win streak
This month: 21W 9L 3D (Blitz)
Peak hours: evenings
Personal best: 1623
Not a table. Not a JSON dump. A story. Because your games are stories and they deserve to be told.
(I know it svcks in visual appeal, we gon fix that).
Card mode — a single SVG image you embed in one line. No GitHub Actions. No workflow. No setup. Just:
Done. It shows your rating, peak rating, win rate, total games, country, and most played opening. Updates on every page load.
The technical bit (for the nerds)
The whole thing runs on Next.js deployed to Vercel. Here's why those two choices specifically:
Next.js gives you API routes and a frontend in one project. My /api/story/[username] and /api/card/[username].svg endpoints live right next to the website that generates the setup instructions. One codebase, One deploy. One git push and everything is live.
Vercel gives you edge deployment for free. This matters specifically for the SVG card — when GitHub renders someone's README, it hits your card endpoint from wherever their CDN node is closest to. Vercel's global network means that request is fast regardless of where the viewer is. A basic Express server on a single DigitalOcean droplet would be slower and more expensive.
The Chess.com API is entirely public and requires zero authentication. You can hit it right now in your browser:
https://api.chess.com/pub/player/hikaru/stats
https://api.chess.com/pub/player/hikaru/games/2026/06
Everything I needed was sitting there. Ratings, game history, PGN strings with opening data baked in, accuracy scores when available, timestamps, country. No API key. No rate limit I hit in practice. Chess.com just... gives you this data. Genuinely one of the nicest public APIs I've worked with.
The trickiest part was the opening name. Chess.com's PGN has an [ECOUrl] header that looks like:
https://www.chess.com/openings/Sicilian-Defense-Dragon-Variation
You slug-parse that URL, replace hyphens with spaces, handle the ... notation for Black's variations, and you have a clean opening name. Much more reliable than the [Opening] header which only appears sometimes.
The second trickiest part was the streak calculation. A chess player plays Blitz, Rapid, and Bullet all mixed together in one games array. If I walked backwards counting consecutive wins, a Rapid loss would break a Blitz win streak incorrectly. The fix is filtering by time_class before counting — only count streaks within the same format as the last game played.
How to set it up in 2 minutes
Go to chess-readme-stats.vercel.app, enter your Chess.com username, and the site generates everything for you — a live preview of your card, the one-line embed, and the complete workflow YAML with your username already filled in.
For card mode: copy one line, paste into README, done.
For story mode: paste the token comments into your README, create one workflow file, run it once manually. After that it runs itself. Don't worry, as of writing this, I need the project is too pre-stage, but I'll maintain it
The whole setup takes less time than the average chess game.
Contribute
This is open source and I genuinely want contributors. There are real features missing that I haven't built yet:
- Light mode card theme
- More custom card themes
- Blitz and Bullet rating variants (currently only Rapid)
- Rating history sparkline inside the card
- Lichess support for the non-Chess.com crowd
- Country code to full country name (right now it shows
INnotIndia) - Response caching so we're not hammering Chess.com on every request
If any of those sound interesting, the codebase is small — under 400 lines total across two route files and one page. You can read the whole thing in 20 minutes and ship something real.
github.com/sxryadipta/chess-readme-stats
The real reason I built this
I'm a fresher. I'm building my portfolio. I needed projects that weren't todo apps or weather apps or Netflix clones.
This is a real product with a real API, a real deployment, real users, and a real open source presence. I learned Next.js by building it. I learned API design by building it. I learned why cache headers matter by being burned by them at midnight.
That's worth more than any tutorial. More importantly, that was something I cared about; and wished it existed
Also my Chess.com stats are now on my GitHub profile and I feel 15% more legitimate as a person.
Built with Next.js, deployed on Vercel, powered by the Chess.com public API.
If this was useful, a star on the repo means a lot — github.com/sxryadipta/chess-readme-stats
Top comments (0)