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:

Argument	Description	Default
`PATH`	Path to your project directory	`.` (current dir)

Options:

Flag	Description
`--template, -t`	Template: `minimal`, `standard`, `full`, `academic`
`--ai, -a, --grok`	Use Groq AI to generate the README
`--auto-ai`	Auto-use AI when API key is available
`--output, -o`	Output filename (default: `README.md`)
`--depth, -d`	Max folder tree depth (1–10, default: 3)
`--no-badges`	Disable shields.io badge generation
`--force, -f`	Overwrite existing README without confirmation
`--dry-run`	Print README to terminal, don't save to file

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:

Flag	Description
`--ai, -a, --grok`	Use AI generation during interactive session

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

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

Option 2 — Create Normal README

Choose mode: 1 (quick generate) or 2 (interactive)
In interactive mode you can customize: author name, GitHub username, template, and whether to include the folder tree
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:

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

Styles:

#	Style	Description
1	Basic	Clean, minimal, professional
2	Professional	Career-focused with detailed sections
3	Stylish	Stats cards, typing effects, badges
4	Unique	Most detailed, creative, and eye-catching

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:

Visit console.groq.com/keys
Click Create Key
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

Template	Best For	Sections
minimal	Small utilities, scripts	Title, description, install, usage, license
standard	Most projects	Overview, prerequisites, install, usage, structure, tests, contributing, license
full	Major applications	Table of contents, features grid, tech stack table, install/usage with copy-ready commands, structure, tests with coverage, contributing, license, footer
academic	Coursework, research	About, objectives checklist, install, run, file structure, concepts, author

# 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:

Key	Type	Default	Description
`template`	string	`"standard"`	Default template name
`output_file`	string	`"README.md"`	Output filename
`include_tree`	bool	`true`	Include folder tree in README
`max_tree_depth`	int	`3`	Maximum tree depth (1–10)
`include_badges`	bool	`true`	Show shields.io badges
`ai_enabled`	bool	`false`	Always use AI generation
`author`	string	`""`	Author name for generated README
`github_username`	string	`""`	GitHub username for repo links

Error Handling

projectreadmegen handles common errors gracefully:

Scenario	Behavior
Path does not exist	Clear error message, exit code 1
Path is a file, not a directory	Clear error message, exit code 1
No read permission	Permission error with actionable guidance
API key missing	Prompts to add one, falls back to template generation
AI generation fails	Automatically falls back to template-based generation
API rate limited	Exponential backoff with retries (up to 3), then clear error
Disk space low	Writes prevented with space requirement info
Invalid config JSON	Error message with JSON syntax details

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

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
Sample		Sample
examples		examples
src/projectreadmegen		src/projectreadmegen
tests		tests
.gitignore		.gitignore
contributing.md		contributing.md
license		license
pyproject.toml		pyproject.toml
readme.md		readme.md
readmegen.config.json		readmegen.config.json
requirements.txt		requirements.txt
security.md		security.md

Folders and files

Latest commit

History

Repository files navigation

PROJECT README GEN

Overview

Features

Installation

Quick Start

Generate a README for any project

Commands

generate — Generate a README

interactive — Interactive customization

start — Launch the interactive menu

version — Show version

update — Check and apply updates

Interactive Menu

Option 1 — Create README with AI

Option 2 — Create Normal README

Option 3 — Manage API Key

Option 4 — View Credits Status

Option 5 — Update

Option 6 — Help & Commands

Option 7 — Create GitHub Profile README

Option 8 — Exit

GitHub Profile README

What it does:

Styles:

Example flow:

API Key Setup

Get your key:

Set it:

Templates

Configuration

Error Handling

Examples

Generate README for a Python project

Generate README for a web app

Preview before saving

AI-powered (with API key)

Project Structure

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`generate` — Generate a README

`interactive` — Interactive customization

`start` — Launch the interactive menu

`version` — Show version

`update` — Check and apply updates

Packages