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

Rudra Malvankar — Sun, 18 Oct 2026 15:44:27 +0000

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.
The "Curse of Knowledge": Authors assume newcomers already understand runtime dependencies, ports, and configuration.
Archaeological Expeditions: Finding out how to run or import a project requires digging through source code.

Core Features

7-Dimension Documentation Health Audit: Evaluates Clarity, 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 () 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:

🚀 Live Production App (Render): https://readmeroast.onrender.com/
⚡ Alternative Deployment (Vercel): https://readmeroast.vercel.app/

How To Try It:

Paste any public GitHub repository URL (e.g. https://github.com/facebook/react or https://github.com/vercel/next.js).
Review your score, read the roast, and inspect the health matrix.
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:

RudraMalvankar / ReadMeRoast

ReadMeRoast 🔥

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.
Archaeological Discovery: Discovering how to actually run or import a package requires digging through source files.
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…

View on GitHub

GitHub Repository: https://github.com/RudraMalvankar/ReadMeRoast

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-weight Gemma 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 through Zod 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 generated only 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 with remark-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.

DEV Community: Rudra Malvankar