I Built an AI CLI Tool That Generates Beautiful READMEs Automatically

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:

1. Scans your project recursively (respects .gitignore)
2. Detects tech stack, languages, and project type
3. Infers commands (install, build, test, run)
4. 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

If this saves you time, I'd love a ⭐ star on GitHub!

💬 Questions?

• What's your biggest pain point with documentation?
• Would you use a tool like this?
• What features would you add?

Drop your thoughts in the comments! 👇

Generated with ❤️ by README-AI-Gen