Your README is probably bad. Let's find out. 🔥

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

#

What I Built

ReadMeRoast is a developer tool and open-source documentation auditor built for the Hacktoberfest Open-Source AI Challenge (Week 2: Side Hustle).

It takes any public GitHub repository URL, audits its README.md using Google's open-weight Gemma 2 model, calculates an objective documentation health score across 7 key pillars, delivers a witty and constructive roast, pinpoints exact documentation gaps, and provides an on-demand, zero-hallucination improved README that developers can immediately ship.

The Problem It Solves

Great open-source repositories often struggle to gain adoption because of poor documentation:

Decorative Badge Overload : 20 status badges at the top, but no clear installation instructions. 2. The "Curse of Knowledge" : Authors assume newcomers already understand runtime dependencies, ports, and configuration. 3. Archaeological Expeditions : Finding out how to run or import a project requires digging through source code.

Core Features

7-Dimension Documentation Health Audit : EvaluatesClarity, Documentation Completeness, Setup & Installation, Usage, Examples, Visual Presentation, and Developer Experience . #

Constructive, Savage Roasts : Unvarnished, humorous developer critique targeting documentation shortcomings, never the person. #

Prioritized Action Plan : High-ROI, numbered recommendations showing developers exactly what to fix first. #

On-Demand Zero-Hallucination Rewrite : Gemma restructures verified project facts and inserts clear developer placeholders (<!-- [TODO: ...] --> ) for missing items without inventing fake commands or APIs. #

Interactive Developer UI : Linear/Vercel-inspired dark theme, circular SVG gauges, side-by-side code editor with line numbers, and instant one-click copy and.md export.

#

Demo

Experience ReadMeRoast live:

How To Try It:

1. Paste any public GitHub repository URL (e.g. https://github.com/facebook/react orhttps://github.com/vercel/next.js ).
2. Review your score, read the roast, and inspect the health matrix.
3. Click "Fix My README" to generate the improved Markdown side-by-side with live line numbers and copy or download the file.

#

Code

ReadMeRoast is 100% open source under the MIT License:

Your README is probably bad. Let's find out. 🔥

ReadMeRoast is a focused developer tool built for the Hacktoberfest Open-Source AI Challenge (Week 2: Side Hustle). It analyzes public GitHub repository READMEs using an open-weight Gemma 2 model, scores documentation health across 7 key dimensions, delivers a hilarious yet constructive roast, identifies documentation blindspots, provides actionable fixes, and generates a zero-hallucination rewritten README in one click.

⚡ The Problem & Solution #

Most developer documentation suffers from three fatal problems:

Decorative Badge Bloat : Badges and status shields take up screen space while installation commands are omitted. 2. Archaeological Discovery : Discovering how to actually run or import a package requires digging through source files. 3. The "Curse of Knowledge" : Authors assume contributors already understand runtime dependencies and environment setup.

ReadMeRoast solves this in 10 seconds:

Paste a public GitHub repo URL — no signups, no auth tokens, no…

#

How I Built It

ReadMeRoast is architected around open-weight AI, serverless route handlers, and strict defensive data parsing:

1. The AI Engine (Gemma 2)

Model : Google's open-weightGemma 2 (gemma-2-27b-it) , accessed through Google AI Studio / Groq with pluggable local fallback support (Ollama / vLLM). #

Isolated Service Layer : AI logic is isolated behind a clean abstraction boundary (lib/ai/client.ts ,lib/ai/analyze-readme.ts ,lib/ai/improve-readme.ts ). #

Strict Schema Enforcement : Responses are validated and clamped throughZod schemas to guarantee valid JSON and prevent malformed UI states. #

Zero Token Waste (On-Demand Generation) : The initial repository audit uses only a single analysis prompt. The complete README rewrite is generatedonly when the user clicks the "Fix My README" button , preventing wasteful background API calls.

2. Full-Stack Tech Stack

Framework : Next.js 16 (App Router) with React 19 and TypeScript. #

Styling : Tailwind CSS v4 with custom dark mode variables, subtle grid backgrounds, and restrained developer-tool typography. #

Data Ingestion : GitHub REST API v3 for decoding base64 README contents, metadata, stars, forks, and languages without cloning repositories. #

Markdown Rendering :react-markdown withremark-gfm for tables, badges, and code blocks. #

Confetti Engine :canvas-confetti triggered when repositories achieve a score of 80+/100.

#

Why Does Open Innovation Matter?

Open-weight models like Gemma 2 empower individual builders and open-source communities in ways closed proprietary APIs cannot:

Freedom from Vendor Lock-In : With open weights, developers control their roadmap without fear of sudden price hikes, deprecated endpoints, or arbitrary API restrictions. #

Local & Air-Gapped Privacy : While ReadMeRoast currently analyzes public repositories, open-weight models allow teams to self-host the service on internal private infrastructure (via Ollama or vLLM) to audit proprietary codebases without sending documentation to third parties. #

Predictable, Cost-Effective Scale : Open-weight innovation democratizes advanced AI capabilities, allowing solo indie hackers to build production-grade developer utilities at near-zero marginal cost.

#

My Agent Session

ReadMeRoast was designed and implemented using an autonomous AI pair-programming workflow:

Architecture & UI Design : Built from scratch using modern developer-tool conventions inspired by GitHub, Linear, and Vercel. #

Strict Zero-Hallucination Testing : Validated against real repositories with varying documentation quality (facebook/react ,vercel/next.js , and minimal repos) to test truncation, error fallbacks, and schema recovery. #

Automated Verification : Created an end-to-end verification suite covering URL parsing, Zod contract clamping, and fallback states.

#

My First User

I shared ReadMeRoast with fellow open-source contributors getting their projects ready for Hacktoberfest:

"I ran my CLI library through ReadMeRoast and it roasted me for having 12 status badges and literally zero install commands for Windows users. The score was a humbling 64/100, but clicking 'Fix My README' gave me an organized Quick Start section with copyable npm commands. I merged the rewrite right away."

— Beta Tester

By combining humorous critique with an instant, ready-to-ship fix, ReadMeRoast turns tedious documentation maintenance into a 30-second win.

#

Prize Categories

Gemma : Gemma 2 is used as the core open-weight AI model for README analysis and improvement. #

Render : ReadMeRoast is deployed and publicly accessible through Render.

source & further reading

dev.to — original article PROVENANCE — I Built an Offline AI Antique Appraiser That Runs in a Basement with No Signal ClauseClear: Gemma 3 1B flags the risky clauses in your client contract, privately How to Join a Pure AI Agent Community in 30 Seconds (No Human Needed)