PROJECT README GEN

Auto-generate README files from folder structure with optional AI enhancement using Groq API.

Overview

Point it at any project folder. It scans your directory structure, detects the tech stack, and generates a polished README.md — in seconds.

Two modes:

• Template-based — 4 ready-made templates (minimal, standard, full, academic)
• AI-powered — connects to Groq API for intelligent, project-aware READMEs

Features

• Auto-detection — identifies language, framework, license, project type, install/run commands
• 4 templates — minimal, standard, full, academic — each with varying detail levels
• AI generation — uses Groq's LLM (llama-3.3-70b) for smart, contextual READMEs
• Interactive mode — answers questions to customize output
• GitHub Profile README — generates profile READMEs with stats cards, language graphs, and style presets
• Badge support — automatic language + license badges via shields.io
• Folder tree — includes an ASCII directory tree in your README
• Safe writes — atomic file writes via temp file + move, disk space checks, permission validation
• Smart caching — reuses previous scan results when project hasn't changed

Installation

pip install projectreadmegen

Verify it installed correctly:

projectreadmegen --version

Or run via Python module:

python -m projectreadmegen --version

Quick Start

Generate a README for any project

# Navigate to your project
cd my-project

# Generate a README using the standard template
projectreadmegen generate .

# Generate with AI (requires API key — see setup below)
projectreadmegen generate . --ai

That's it. Your README.md is created in the current directory.

Commands

All commands support --help for inline documentation.

generate — Generate a README

The primary command. Scans a project directory and writes README.md.

projectreadmegen generate [PATH] [OPTIONS]

Arguments:

Options:

Examples:

# Basic — standard template
projectreadmegen generate .

# Choose a template
projectreadmegen generate . --template full
projectreadmegen generate . -t minimal

# AI-powered README
projectreadmegen generate . --ai

# Include folder tree up to 5 levels deep
projectreadmegen generate . --depth 5

# Preview without saving
projectreadmegen generate . --dry-run --template full

# Custom output file
projectreadmegen generate . --output PROFILE.md

# Disable badges
projectreadmegen generate . --no-badges

# Overwrite existing README silently
projectreadmegen generate . --force

# All flags together
projectreadmegen generate ./my-project -t full --ai --depth 4 --no-badges --output README.md

interactive — Interactive customization

Walks you through questions to customize the generated README.

projectreadmegen interactive [PATH] [OPTIONS]

Options:

Example workflow:

# Template-based interactive
projectreadmegen interactive .
# Asks for: your name, GitHub username, template choice, include tree?

# AI-powered interactive
projectreadmegen interactive . --ai
# Uses AI to generate, falls back to template if API key is missing

start — Launch the interactive menu

Opens the full-featured menu system shown below in the Interactive Menu section.

projectreadmegen start

version — Show version

projectreadmegen version
projectreadmegen --version
projectreadmegen -V

update — Check and apply updates

projectreadmegen update

Checks PyPI for a newer version and upgrades automatically if one exists.

Interactive Menu

Run projectreadmegen start to open the menu:

┌──────────────────────────────────────────────┐
│         Welcome to projectreadmegen           │
│   Auto-generate README files with AI power    │
│                                              │
│  Select an option:                           │
│                                              │
│  1  Create README with AI                     │
│  2  Create Normal README (template-based)     │
│  3  Manage API Key                           │
│  4  View Credits Status                      │
│  5  Update projectreadmegen                   │
│  6  Help & Commands                          │
│  7  Create GitHub Profile README  [NEW]       │
│  8  Exit                                     │
└──────────────────────────────────────────────┘

Option 1 — Create README with AI

1. Choose mode: 1 (quick generate) or 2 (interactive)
2. Enter project path (or press Enter for current dir)
3. If no API key is detected, you'll be prompted to add one
4. README is generated via Groq AI and saved

Option 2 — Create Normal README

1. Choose mode: 1 (quick generate) or 2 (interactive)
2. In interactive mode you can customize: author name, GitHub username, template, and whether to include the folder tree
3. README is generated from templates and saved

Option 3 — Manage API Key

• If no key configured: Add your own Groq API key or manage a GitHub token
• If key configured: Update, remove, or manage GitHub token
• API keys must start with gsk_ and are stored locally in %APPDATA%\projectreadmegen\ (Windows) or ~/.projectreadmegen/

Option 4 — View Credits Status

Shows whether your Groq API key and GitHub token are configured.

Option 5 — Update

Same as the update command — checks PyPI for the latest version.

Option 6 — Help & Commands

Quick reference of all CLI commands and flags.

Option 7 — Create GitHub Profile README

See dedicated section below.

Option 8 — Exit

Exits the menu.

GitHub Profile README

Generates a README for your github.com/<username> profile repository.

Access via: Menu option 7 or programmatically through the github_profile module.

What it does:

1. Asks for your GitHub username and profile URL
2. Fetches your profile data, repositories, and language stats via the GitHub API
3. Lets you choose a style
4. Generates an AI-powered profile README using Groq

Styles:

Example flow:

# Via menu
projectreadmegen start
# Select option 7, enter username, choose style

# The tool:
# 1. Validates the GitHub username
# 2. Fetches profile data from api.github.com
# 3. Generates README with shields.io badges and stats cards
# 4. Saves to ./<username>/README.md

Note: Requires a Groq API key. A GitHub token is optional but enables richer data (all repos, accurate stats).

API Key Setup

AI features require a free Groq API key.

Get your key:

1. Visit console.groq.com/keys
2. Click Create Key
3. Copy the key (starts with gsk_)

Set it:

Via the menu:

projectreadmegen start
# Select option 3 → Add Your Own API Key

Via environment variable (recommended for scripts):

# PowerShell
$env:GROQ_API_KEY = "gsk_your_key_here"

# CMD
set GROQ_API_KEY=gsk_your_key_here

The key is stored locally and used for all AI features (README generation, GitHub Profile README).

Templates

# Specify a template
projectreadmegen generate . --template academic
projectreadmegen generate . -t full

The last-used template per project is remembered (stored in the local cache).

Configuration

Create a readmegen.config.json in your project root to set persistent defaults:

{
  "template": "standard",
  "output_file": "README.md",
  "include_tree": true,
  "max_tree_depth": 3,
  "include_badges": true,
  "author": "",
  "github_username": "your-username"
}

Available keys:

Error Handling

projectreadmegen handles common errors gracefully:

Examples

Generate README for a Python project

cd my-python-project
projectreadmegen generate . --template full
# Output: ./README.md with title, description, install/run commands, folder tree

Generate README for a web app

projectreadmegen generate ./react-app --template full --depth 5
# Detects: React, TypeScript, npm
# Includes: tech stack table, full feature list, folder tree

Preview before saving

projectreadmegen generate . --dry-run --template standard
# Prints the generated README to the terminal

AI-powered (with API key)

projectreadmegen generate . --ai
# Sends project context to Groq API, receives a customized README

Project Structure

projectreadmegen/
├── src/
│   └── projectreadmegen/
│       ├── __init__.py          # Version info
│       ├── __main__.py          # Entry: python -m projectreadmegen
│       ├── cli.py               # CLI commands, menu system
│       ├── badges.py            # shields.io badge generation
│       ├── config.py            # Language patterns, skip lists, defaults
│       ├── detector.py          # Language, license, project type detection
│       ├── exceptions.py        # Custom exception hierarchy
│       ├── generator.py         # Template rendering + file writing
│       ├── github_profile.py    # GitHub profile README generation
│       ├── grok.py              # Groq AI client with retry logic
│       ├── scanner.py           # Directory traversal + caching
│       ├── usagetracker.py      # API key storage, usage tracking
│       ├── utils.py             # Path validation, symlink checks, disk space
│       └── templates/
│           ├── minimal.md.j2
│           ├── standard.md.j2
│           ├── full.md.j2
│           └── academic.md.j2
├── tests/
│   ├── test_detector.py
│   ├── test_generator.py
│   ├── test_github_profile.py
│   ├── test_scanner.py
│   └── test_usagetracker.py
├── examples/                   # Sample projects for testing detection
├── pyproject.toml
├── readmegen.config.json
└── readme.md

© 2026 Zenith Open Source Projects. All Rights Reserved. Zenith is a Open Source Project Idea's by @roshhellwett