Automated README file generator, powered by LLM APIs
Objective
Readme-ai is a developer tool that auto-generates README.md files using a combination of data extraction and generative ai. Simply provide a repository URL or local path to your codebase and a well-structured and detailed README file will be generated for you.
Motivation
Streamlines documentation creation and maintenance, enhancing developer productivity. This project aims to enable all skill levels, across all domains, to better understand, use, and contribute to open-source software.
Important
Readme-ai is currently under development with an opinionated configuration and setup. It is vital to review all text generated by the LLM APIs to ensure it accurately represents your project.
Standard CLI usage, providing a repository URL to generate a README file.
readmeai-cli-demo.mov
Generate a README file without making API calls using the --offline CLI option.
readmeai-streamlit-demo.mov
Tip
Offline mode is useful for generating a boilerplate README at no cost. View the offline README.md example here!
Built with flexibility in mind, readme-ai allows users to customize various aspects of the README using CLI options and configuration settings. Content is generated using a combination of data extraction and making a few calls to LLM APIs.
Currently, readme-ai uses generative ai to create four sections of the README file.
i. Header: Project slogan that describes the repository in an engaging way.
ii. Overview: Provides an intro to the project's core use-case and value proposition.
iii. Features: Markdown table containing details about the project's technical components.
iv. Modules: Codebase file summaries are generated and formatted into markdown tables.
All other content is extracted from processing and analyzing repository metadata and files.
The header section is built using repository metadata and CLI options. Key features include:
- Badges: Svg icons that represent codebase metadata, provided by shields.io and skill-icons.
- Project Logo: Select a project logo image from the base set or provide your image.
- Project Slogan: Catch phrase that describes the project, generated by generative ai.
- Table of Contents/Quick Links: Links to the different sections of the README file.
See a few examples headers generated by readme-ai below.
 default output (no options provided to cli)
|
|
 --align left --badges flat-square --image cloud
|
 --align left --badges flat --image gradient
|
 --badges flat --image custom
|
 --badges skills-light --image grey
|
 --badges flat-square
|
 --badges flat --image black
|
See the Configuration section below for the complete list of CLI options and settings.
📑 Codebase Documentation
|
Repository Structure A directory tree structure is generated using pure Python (tree.py) and embedded in the README. |
|
|
Codebase Summaries
Code summaries are generated using LLMs and grouped by directory, displayed in markdown tables. |
|
📍 Overview & Features Table
The overview and features sections are generated using LLM APIs. Structured prompt templates are injected with repository metadata to help produce more accurate and relevant content.
| Overview High-level introduction of the project, focused on the value proposition and use-cases, rather than technical aspects. |
 |
| Features Table Describes technical components of the codebase, including architecture, dependencies, testing, integrations, and more. |
 |
🚀 Dynamic Quickstart Guides
| Getting Started or Quick Start Generates structured guides for installing, running, and testing your project. These steps are created by identifying dependencies and languages used in the codebase, and mapping this data to configuration files such as the language_setup.toml file. |
|
🤝 Contributing Guidelines & More
| Additional Sections The remaining README sections are built from a baseline template that includes common sections such as |
 |
| Contributing Guidelines The contributing guidelines has a dropdown that outlines a general process for contributing to your project. |
 |
🧩 Template READMEs
This feature is currently under development. The template system will allow users to generate README files in different flavors, such as ai, data, web development, etc.
|
| ⭑ | Output File 📄 | Input Repository 📁 | Repository Type 🔢 |
|---|---|---|---|
| ⭑ | readme-python.md | readme-ai | Python |
| ⭑ | readme-typescript.md | chatgpt-app-react-ts | TypeScript, React |
| ⭑ | readme-postgres.md | postgres-proxy-server | Postgres, Duckdb |
| ⭑ | readme-kotlin.md | file.io-android-client | Kotlin, Android |
| ⭑ | readme-streamlit.md | readme-ai-streamlit | Python, Streamlit |
| ⭑ | readme-rust-c.md | rust-c-app | C, Rust |
| ⭑ | readme-go.md | go-docker-app | Go |
| ⭑ | readme-java.md | java-minimal-todo | Java |
| ⭑ | readme-fastapi-redis.md | async-ml-inference | FastAPI, Redis |
| ⭑ | readme-mlops.md | mlops-course | Python, Jupyter |
| ⭑ | readme-pyflink.md | flink-flow | PyFlink |
Requirements
- Python: 3.9+
- Package manager or container runtime:
pipordockerrecommended. - LLM API key: currently OpenAI and Google Cloud are supported.
Repository
A repository URL or local path to your codebase is required run readme-ai. The following are supported:
OpenAI API Key
An OpenAI API account and API key are needed to use readme-ai. Get started by creating an account here. Once you have an account, you can create an API key on the API settings page.
Warning
Before using readme-ai, its essential to understand the potential risks and costs associated with using AI-powered tools.
-
Review Sensitive Information: Ensure all content in your repository is free of sensitive information before running the tool. This project does not remove sensitive data from your codebase, nor from the output README file.
-
API Usage Costs: The OpenAI API is not free and costs can accumulate quickly! You will be charged for each request made by readme-ai. Be sure to monitor API usage costs using the OpenAI API Usage Dashboard.
pip install readmeai
docker pull zeroxeli/readme-ai:latest
conda install -c conda-forge readmeai
Clone repository and change directory.
$ git clone https://github.com/eli64s/readme-ai $ cd readme-ai
$ bash setup/setup.sh
$ poetry install
- Similiary you can use
pipenvorpipto install the requirements.txt.
Before running the CLI, ensure you export your OpenAI API key as an environment variable.
On Linux or MacOS
$ export OPENAI_API_KEY=YOUR_API_KEYOn Windows
$ set OPENAI_API_KEY=YOUR_API_KEY
readmeai --repository https://github.com/eli64s/readme-ai
docker run -it \ -e OPENAI_API_KEY=$OPENAI_API_KEY \ -v "$(pwd)":/app zeroxeli/readme-ai:latest \ -r https://github.com/eli64s/readme-ai
Use the app directly in your browser on Streamlit, no installation required! More details about the web app can be found here.
$ conda activate readmeai $ python3 -m readmeai.cli.commands -r https://github.com/eli64s/readme-ai
$ poetry shell $ python3 -m readmeai.cli.commands -r https://github.com/eli64s/readme-ai
$ make pytest
$ nox -f noxfile.py
Tip
Use nox to test application against multiple Python environments and dependencies!
Run the readmeai command in your terminal with the following options to tailor your README file.
| Option | Description | Values | Default Value | Data Type |
|---|---|---|---|---|
--align, -a |
Align the text in the README.md file's header. | center, left |
center |
String |
--api-key |
LLM API key to generate text for the README.md file. | String | ||
--badges, -b |
Badge icon style types for README.md badges. | flat, flat-square, for-the-badge, plastic, skills, skills-light, social |
default |
String |
--emojis, -e |
Adds emojis to the README.md file's header sections. | False |
Boolean | |
--image, -i |
Project logo image displayed in the README file header. | CUSTOM, BLACK, GRADIENT, GREY, PURPLE, YELLOW, CLOUD |
DEFAULT |
String |
🚧 --language |
Language for generating the README.md file. | en |
String | |
--max-tokens |
Maximum number of tokens for each section of the README.md file. | Integer | ||
--model, -m |
GPT language model for generating various sections of the README.md file. | String | ||
--offline |
Generates a README.md file without API calls, with placeholders for generated content. | False |
Boolean | |
--output, -o |
Output file name for the README file. | readme-ai.md |
String | |
--repository, -r |
Remote repository URL or local directory path for the project. | String | ||
--temperature, -t |
Sets the creativity level for content generation. | 0.0 to 2.0 |
1.0 |
Float |
🚧 --template |
README template file for generating the README.md file. | String | ||
--vertex_ai |
Google Vertex AI configuration, requires location and project ID. | Tuple (String) | ||
--help |
Displays help information about the command and its options. |
🚧 feature currently under development
The --badges option lets you select the style of the default badge set.
| Style | Preview |
|---|---|
default |
    |
flat |
 |
flat-square |
 |
for-the-badge |
 |
plastic |
 |
skills |
|
skills-light |
|
social |
 |
When providing the --badges option, readme-ai does two things:
- Formats the default badge set to match the selection (i.e. flat, flat-square, etc.).
- Generates an additional badge set representing your projects dependencies and tech stack (i.e. Python, Docker, etc.)
$ readmeai --badges flat-square --repository https://github.com/eli64s/readme-ai
{... project logo ...}
{... project name ...}
{...project slogan...}
Developed with the software and tools below.
{... end of header ...}
Select a project logo using the --image option. The following options are available:
default |
gradient |
black |
 |
|
 |
cloud |
purple |
grey |
 |
 |
 |
Use the --image custom option to ivoke a prompt to enter a custom image URL or path.
- Publish readme-ai CLI as a Python package on PyPI.
- Containerize the readme-ai CLI as a Docker image via Docker Hub.
- Serve the readme-ai CLI as a web app, deployed on Streamlit Community Cloud.
- Integrate singular interface for all LLM API providers (Anthropic, Cohere, Gemini, etc.)
- Design template system to give users a variety of README document flavors (ai, data, web, etc.)
- Develop robust documentation generation process to extend to full project docs (i.e. Sphinx, MkDocs, etc.)
- Add support for generating README files in any language (i.e. CN, ES, FR, JA, KO, RU).
- Create GitHub Actions script to automatically update README file content on repository push.
Badges