greadme 0.1.4

Generate README files using AI

README Generator (greadme)

CLI tool that reads your project structure, dependencies and source files, then writes the README for you, using AI models.

Badges

Table of Contents

• README Generator (greadme)
  • Badges
  • Table of Contents
  • Overview
    • Project Demonstration
  • Key Features
  • Technical Stack
  • Architecture
    • Directory Structure
    • Data Flow
    • System Components
  • Getting Started
    • Prerequisites
    • Installation
    • Configuration
  • Usage
  • Customization Options
    • Configuration File Options
    • Command-Line Arguments (greadme gen subcommand)
  • Author
  • License

Overview

The README Generator greadme addresses the common challenge faced by developers in creating and maintaining detailed, accurate README.md files for their projects. Manually documenting a project's purpose, architecture, dependencies, and usage can be a time-consuming and often overlooked task. This tool automates the process by leveraging artificial intelligence to analyze a project's codebase and infer all necessary details, thereby enabling developers and open-source maintainers to quickly generate high-quality documentation.

At its core, the project operates by scanning a target directory to understand its structure, programming language, and dependencies. It then compiles this contextual information into a prompt, which is subsequently sent to a large language model (Gemini, OpenAI or Groq API). The AI processes the prompt and generates a comprehensive README.md tailored to the project. The tool also incorporates configurable settings for the AI model, API keys, and output language, ensuring flexibility and ease of use.

The README Generator stands out by providing an intelligent, automated solution to documentation generation, significantly reducing the manual effort involved. Its ability to infer crucial project details directly from the source code, coupled with support for multiple output languages and integration with .gitignore rules, ensures that the generated documentation is not only rich in detail but also relevant and concise. This approach minimizes setup time and maximizes productivity for developers looking to present their projects professionally.

It is also important that the user always reads and reviews the file generated by the AI, as it may contain errors or convey incorrect and false information.

Project Demonstration

Key Features

• AI-Powered Generation: Automatically generates detailed README.md files by leveraging a configured AI model (Google Gemini, Groq or OpenAI).
• Intelligent Project Scanning: Detects project type, extracts file structure, identifies dependencies, and reads relevant source file content.
• Configurable Settings: Supports persistent configuration for AI API keys, default README language (English/Portuguese), and GitHub username.
• Command-Line Interface: Provides an intuitive CLI for initiating README generation and managing application settings.
• .gitignore Integration: Respects .gitignore rules during project scanning to exclude irrelevant files and directories from analysis.
• Multilingual Output: Generates README.md files in either English (en) or Portuguese (pt) based on user preference.

Technical Stack

• Programming Language: Python 3.11+
• Frameworks and Libraries:
  • argparse (Python standard library for command-line argument parsing)
  • pathlib (Python standard library for object-oriented filesystem paths)
  • tomllib (Python standard library for parsing TOML files, used for configuration)
  • json (Python standard library for JSON data handling, used for Node.js dependency scanning)
  • xml.etree.ElementTree (Python standard library for XML parsing, used for Java dependency scanning)
  • Google Gemini API (genai)
  • OpenAI (openai)
• Data Persistence: Local .toml configuration file (config.toml)
• Build and Deployment Tools: Standard Python packaging and execution mechanisms.
• Other relevant technologies: File system interaction for project scanning and output writing.

Architecture

The README Generator is designed with a modular architecture, separating concerns into distinct components for project scanning, configuration management, AI prompting, and command-line interface handling.

Directory Structure

greadme/                 # Main application package
  cli.py                 # Command-Line Interface: entry point, argument parsing, orchestration
  config.py              # Configuration Manager: handles loading, saving, and managing application settings
  scanner.py             # Project Scanner: analyzes project directory, infers type, structure, dependencies
  builder.py             # Prompt Builder: constructs the AI prompt from scanned project context
  ai.py                  # AI Interface: communicates with the AI API
  templates/             # Templates for AI prompts
    en.md                # English prompt template
    pt.md                # Portuguese prompt template

Data Flow

The following sequence diagram illustrates the primary data flow when generating a README.md file:

sequenceDiagram
    autonumber
    participant User
    participant CLI(greadme)
    participant ConfigManager
    participant ProjectScanner
    participant PromptBuilder
    participant AIModel
    participant FileSystem

    User->>CLI(greadme): Initiates README generation via 'greadme gen' command
    CLI(greadme)->>ConfigManager: Loads persistent configuration (api_key, provider, lang, github_user)
    ConfigManager-->>CLI(greadme): Returns application settings
    CLI(greadme)->>CLI(greadme): Overrides config with command-line arguments if provided
    CLI(greadme)->>ProjectScanner: Scans the specified project path
    ProjectScanner->>ProjectScanner: Loads and applies '.gitignore' rules
    User->>ProjectScanner: Project name, repository name, and description (obtained directly from the user)
    ProjectScanner->>ProjectScanner: Gathers file tree, dependencies, and content of relevant files
    ProjectScanner-->>CLI(greadme): Returns comprehensive project context
    CLI(greadme)->>PromptBuilder: Builds an AI prompt using the project context and desired language
    PromptBuilder-->>CLI(greadme): Returns the structured AI prompt
    CLI(greadme)->>AIModel: Sends the LLM provider, AI prompt, configured model, and API key to the AI service
    AIModel-->>CLI(greadme): Returns the generated README content
    CLI(greadme)->>FileSystem: Writes the generated content to 'README.md' or specified output path
    FileSystem-->>CLI(greadme): Confirms file save operation
    CLI(greadme)-->>User: Displays success or error message

System Components

• CLI Module (greadme.cli): Serves as the primary entry point for the application. It handles command-line argument parsing using argparse and orchestrates the workflow by coordinating calls to other modules for scanning, configuration, and AI interaction. It defines the gen and config subcommands.
• Configuration Module (greadme.config): Manages application-wide settings such as the Gemini API key, preferred language, and GitHub username. It loads default values, persists user-defined settings to a config.toml file (located in ~/.config/greadme/ or %APPDATA%\greadme\), and ensures settings are applied consistently.
• Scanner Module (greadme.scanner): This is the intelligence gathering component. It recursively traverses a target project directory, identifies the project's primary language and type, extracts a hierarchical file structure, determines project dependencies by parsing common manifest files (pyproject.toml, requirements.txt, package.json, Cargo.toml, pom.xml, etc.), and reads the contents of key source files. It intelligently ignores common development artifacts and respects .gitignore rules.
• Builder Module (greadme.builder): Responsible for transforming the structured project context obtained from the Scanner into a coherent and effective prompt for the AI model. This module likely uses templates (e.g., en.md, pt.md) to guide the AI in generating a well-structured and informative README.md.
• AI Module (greadme.ai): Acts as the bridge between the application and the external AI service (Google Gemini). It encapsulates the logic for sending prompts, handling API requests, and return the AI responses.

Getting Started

Prerequisites

• Python 3.11+
• Google Gemini API key — get one at Google AI Studio
• OpenAI API key – get one at OpenAI Plataform
• Groq API key – get one at Groq Console

Installation

Install via pip:

pip install greadme

Or with pipx (recommended for global CLI usage):

pipx install greadme

Configuration

Before generating your first README, you need to configure your API key and other preferences. Configuration settings are stored in a config.toml file, typically located at:

• Linux/macOS: ~/.config/greadme/config.toml
• Windows: %APPDATA%\greadme\config.toml

You can manage these settings directly via the command-line interface:

• general.lang: The default language for the generated README (en for English, pt for Portuguese).

  • Default: "en"
  • Example:

    greadme config set general.lang pt
    

• general.github_user: Your GitHub username, used for generating relevant links and information in the README.

  • Default: "" (empty string, causing an error if not set for some features)
  • Example:

    greadme config set general.github_user vinifreitaspaulino
    

• general.provider: Your default LLM provider, used to determine which function will be called. At the moment it could be gemini, groq or openai.

  • Default: "gemini"
  • Example:

    greadme config set general.provider groq
    

• <provider>.api_key: Your API key for the specific provider.

  • Default: "" (empty string, causing an error if not set)
  • Example:

    greadme config set openai.api_key YOUR_API_KEY
    

• <provider>.model: The provider-specific model that will be used by default for that provider.

  • Default: Gemini: "gemini-2.5-flash", Groq: "meta-llama/llama-4-scout-17b-16e-instruct", OpenAI: "gpt-5.4-mini"
  • Example:

    greadme config set gemini.model gemini-2.0-flash-lite
    

To view your current configuration:

greadme config show

Usage

The greadme is primarily controlled via its command-line interface. Once installed and configured, you can generate READMEs for your projects or manage settings.

To generate a README.md for a project:

greadme gen <project_path> [--output <output_path>] [--lang <language>] [--verbose]

or without gen:

greadme <project_path> [--output <output_path>] [--lang <language>] [--verbose]

Examples:

1. Generate a README for the current directory using default settings (default language, default AI model, default provider, configured API key, default output path):

   greadme .
   

2. Generate a README for a specific project path, outputting it in Portuguese:

   greadme ~/my_python_project --lang pt
   

3. Generate a README for a project, saving it to a custom location and enabling verbose output:

   greadme /path/to/the/project --output /path/to/output/folder --verbose
   

4. Override the API key, AI model and provider directly for a single generation command:

   greadme . --api-key ANOTHER_KEY --model gemini-3-flash-preview -p gemini
   

Customization Options

The greadme offers several options for customizing its behavior, both through persistent configuration and command-line arguments.

Configuration File Options

These options are stored in the config.toml file and affect all subsequent greadme commands unless overridden by command-line arguments.

Key	Type	Default	Description
general.lang	String	"en"	Sets the default language for generated README.md files. Supported values are "en" (English) and "pt" (Portuguese).
general.github_user	String	""	Your GitHub username. This is used by the AI to infer author details and construct GitHub-related links within the README. Essential for the badge links.
general.provider	String	"gemini"	Your default LLM model provider, that is, the company or service that provides the model in question. Currently, only Google Gemini, OpenAI, and Groq models are supported.
<provider>.api_key	String	""	Your API key for accessing the provider AI service. This is mandatory for the tool to function and generate READMEs.
<provider>.model	String	"gemini-2.5-flash" and "meta-llama/llama-4-scout-17b-16e-instruct" and "gpt-5.4-mini"	Specifies the particular model to be used for AI generation according to the provider in question. Different models may offer varying performance, cost, and output quality.

Example config.toml snippet:

[general]
lang = "en"
provider = "gemini"
github_user = "vinifreitaspaulino"

[gemini]
api_key = "GEMINI_API_KEY
model = "gemini-2.5-flash"

[groq]
api_key = "GROQ_API_KEY"
model = "meta-llama/llama-4-scout-17b-16e-instruct"

[openai]
api_key = "OPENAI_API_KEY"
model = "gpt-5.4-mini"

Command-Line Arguments (greadme gen subcommand)

These arguments allow for temporary overrides of configured settings or provide specific parameters for a single gen operation. You can also omit gen and pass the path, this is also understood as generating a README.

Argument	Type	Default (or config)	Description
path	Path	Required	The filesystem path to the project directory for which the README should be generated.
--output, -o	Path	<project_path>/README.md	Specifies the full output path, including the filename, for the generated README.md. If not provided, it defaults to README.md in the project root.
--verbose, -v	Flag	False	Activates verbose logging, displaying detailed progress messages during the scanning, prompt building, and AI call phases.
--lang, -l	String	config["general"]["lang"]	Overrides the default language for the generated README for this specific run. Choices are "pt" (Portuguese) or "en" (English).
--api-key	String	config[provider]["api_key"]	Temporarily overrides the ai.api_key configured in config.toml for the current generation command. Useful for testing or managing multiple keys.
--model	String	config[provider]["model"]	Temporarily overrides the ai.model configured in config.toml for the current generation command. Allows for on-the-fly switching between AI models. For it to work, it must be compatible with the provider that will be used.
--provider, -p	String	config["general"]["provider"]	Temporarily overrides the general.provider configured in config.toml for the current generation command. Useful for switching between LLM services quickly and instantly.
--github_user	String	config["general"]["github_user"]	Temporarily overrides the general.github_user configured in config.toml for the current generation command.

These options collectively provide fine-grained control over how greadme operates, allowing users to tailor the generation process to their specific needs and project contexts.

Author

Vinicius de Freitas Paulino

• GitHub: @vinifreitaspaulino

License

This project is licensed under the MIT License.