Ishan Ashu

Posted on Apr 13

I Built an AI CLI Tool That Generates Beautiful READMEs Automatically

#ai #automation #documentation #showdev

We've all been there: you finish building an amazing project, push it to GitHub, and then... stare at a blank README.

Writing good documentation is:

😩 Time-consuming (who wants to write installation steps?)
🤔 Mental overhead (what should I include? How do I structure it?)
⏰ Often skipped (the code works, right? README can wait...)

But a good README is the first impression users get of your project. No README = no users = no stars.

So I asked myself: What if AI could analyze my codebase and generate a professional README automatically?

The Solution: README-AI-Gen

I spent 7 days building README-AI-Gen, an AI-powered CLI tool that:

Scans your project recursively (respects .gitignore)
Detects tech stack, languages, and project type
Infers commands (install, build, test, run)
Generates a beautiful, comprehensive README using AI

🎯 What It Does

$ readme-ai-gen generate ./my-project --interactive

ℹ  Scanning project files...
✓ Found 42 file(s)
ℹ  Project type: Node.js, TypeScript
ℹ  Generating content with AI...
✓ README.md generated successfully!
📝 1,234 words | 8 sections | ~5 min read

The generated README includes:

📖 Overview - Project description and key features
🛠️ Tech Stack - Languages, frameworks, tools with badges
🚀 Commands - Installation, build, test, run instructions
📁 Project Structure - ASCII directory tree with explanations
💻 Usage - How to use your project
📄 License - License section with badge
✨ And more... (Features, API Reference, Contributing, etc.)

🤖 How It Works

The 8-Step Pipeline

readme-ai-gen generate
│
├── Step 1: FileScanner (scan project files)
├── Step 2: TechMapper (detect languages & project types)
├── Step 3: TreeGenerator (ASCII directory tree)
├── Step 4: CommandInference (find build/run commands)
├── Step 5: ContextBuilder (build AI context from key files)
├── Step 6: AIEngine (generate content with AI)
├── Step 7: DataSanitizer (clean & format data)
└── Step 8: MarkdownEngine (assemble final README)

AI Provider Support

The tool works with 5 AI providers:

🔵 OpenRouter (recommended, best model selection)
🟣 OpenAI (GPT-4o, GPT-4o-mini, etc.)
🟢 Anthropic (Claude 3.5 Sonnet, etc.)
🔴 Google Gemini (Gemini 2.5 Pro, Flash, etc.)
🟡 NVIDIA (Nemotron, etc.)

🚀 Quick Start

Installation

# Install from source
git clone https://github.com/ashu90-prog/README-AI-Gen.git
cd README-AI-Gen
npm install
npm run build
npm link

# Or install globally (when published to npm)
npm install -g readme-ai-gen

Usage

# Analyse only (no AI, instant)
readme-ai-gen generate ./my-project --no-ai

# Generate with AI (OpenRouter recommended)
readme-ai-gen generate ./my-project \
  --provider openrouter \
  --model openrouter/auto

# Interactive mode (guided prompts)
readme-ai-gen generate --interactive

# Use a template
readme-ai-gen generate ./my-project --template comprehensive

# Generate with validation & stats
readme-ai-gen generate ./my-project --validate --stats

✨ Features

Analysis

Recursive file scanning with .gitignore support
Project type detection (Node.js, Python, React, Flutter, etc.)
Language breakdown and file counting
Command inference from package.json, scripts, and config files
ASCII directory tree generation

AI Generation

Multi-provider support (OpenAI, Anthropic, Gemini, OpenRouter, NVIDIA)
OpenRouter auto model (best model selection automatically)
Interactive mode with guided prompts
Analysis caching for faster re-runs
Dry-run mode to preview output

Templates & Customization

4 predefined templates (minimal, standard, comprehensive, api-docs)
Custom template support (JSON config)
Badge style control (6 styles + no badges)
Section toggling (include/exclude any section)

Validation & Quality

README validation with error/warning/suggestion system
Detailed statistics (word count, reading time, section count)
Preview in browser/markdown viewer
Markdown linting compliance

📊 Real Example

I ran it on itself (meta!):

readme-ai-gen generate "C:\Users\anand\OneDrive\Documents\Readme Gen" \
  --provider openrouter \
  --model openrouter/auto \
  --template standard \
  --validate \
  --stats

Result:

✓ 39 files analysed
✓ 13 languages detected
✓ 5 commands inferred
✓ README generated: 1,234 words, 8 sections, ~5 min read
✓ All validation checks passed

🛠️ Tech Stack

TypeScript (ESM) - Type-safe, modern JavaScript
Commander - CLI argument parsing
OpenAI SDK - Multi-provider AI integration
fs-extra - File system operations
ignore - .gitignore pattern matching
glob - File pattern matching
chalk - Colored terminal output

🎯 What I Learned

1. AI is Only as Good as Its Context

The biggest challenge wasn't the AI itself—it was building the right context. The tool spends most of its time:

Scanning files intelligently (not blindly reading everything)
Detecting project structure and conventions
Inferring commands from multiple sources
Building a focused context that fits AI token limits

2. Determinism Matters

Users don't want random output every time. The tool uses:

Heuristic fallbacks when AI fails
Validation to ensure quality
Templates for consistent structure
Caching for reproducible results

3. Developer Experience is Everything

I built this tool for developers. Every decision was guided by:

What would I want to use?
What would save me the most time?
What would make documentation less painful?

🔮 What's Next

[ ] Publish to npm for easy installation
[ ] Add more templates (blog-style, changelog, etc.)
[ ] Support for more project types (Rust, Go, Java, etc.)
[ ] GitHub Action for automatic README generation
[ ] Web interface (no CLI needed)

🤝 Try It Out

GitHub: https://github.com/ashu90-prog/README-AI-Gen

git clone https://github.com/ashu90-prog/README-AI-Gen.git
cd README-AI-Gen
npm install
npm run build
npm link
readme-ai-gen generate --interactive

DEV Community