Repository files navigation

Designed for simplicity, customization, and developer productivity.

• Intro
• Demo
• Features
• Quickstart
• Configuration
• Example Gallery
• Contributing Guidelines

ReadmeAI is a developer tool that automatically generates README files using a robust repository processing engine and advanced language models. Simply provide a URL or path to your codebase, and a well-structured and detailed README will be generated.

Why Use ReadmeAI?

This project aims to streamline the process of creating and maintaining documentation across all technical disciplines and experience levels. The core principles include:

• 🔵 Automate: Generate detailed and structured README files with a single command.
• ⚫️ Customize: Select from a variety of templates, styles, badges, and much more.
• 🟣 Flexible: Switch betweenOpenAI,Ollama,Anthropic, andGemini anytime.
• 🟠 Language Agnostic: Compatible with a wide range of languages and frameworks.
• 🟡 Best Practices: Ensure clean and consistent documentation across all projects.
• 🟢 Smart Filtering: Intelligent file analysis with customizable.readmeaiignore patterns.
• ⛔️ Offline Mode: Create README files offline, without using a LLM API service.

Run from your terminal:

Let's begin by exploring various customization options and styles supported by ReadmeAI:

Header Styles

CLI Command: $ readmeai --repository https://github.com/eli64s/readme-ai-streamlit \  --logo custom \  --badge-color FF4B4B \  --badge-style flat-square \  --header-style classic

CLI Command: $ readmeai --repository https://github.com/olliefr/docker-gs-ping \  --badge-color 00ADD8 \  --badge-style for-the-badge \  --header-style modern \  --navigation-style roman

CLI Command: $ readmeai --repository https://github.com/rumaan/file.io-Android-Client \  --badge-style plastic \  --badge-color blueviolet \  --logo PURPLE \  --header-style COMPACT \  --navigation-style NUMBER \  --emojis solar

Banner Styles

CLI Command: $ readmeai --repository https://github.com/emcf/thepipe \  --badge-style flat-square \  --badge-color 8a2be2 \  --header-style console \  --navigation-style accordion \  --emojis water

CLI Command: $ readmeai --repository https://github.com/FerrariDG/async-ml-inference \  --badge-style plastic \  --badge-color 43a047 \  --header-style BANNER

And More!

CLI Command: $ readmeai --repository 'https://github.com/eli64sreadme-ai-streamlit' \  --badge-style FLAT-SQUARE \  --badge-color E92063 \  --header-style COMPACT \  --navigation-style ACCORDION \  --emojis RAINBOW \  --logo ICE

CLI Command: $ readmeai --repository https://github.com/jwills/buenavista \  --align LEFT \  --badge-style FLAT-SQUARE \  --logo CUSTOM

꩜ Expand to view more!

Project Introduction This section captures your project's essence and value proposition. The prompt template used to generate this section can be viewedhere.

Features Table Detailed feature breakdown and technical capabilities. The prompt template used to generate this section can be viewedhere.

Project Structure Visual representation of your project's directory structure. The tree is generated usingpure Python and embedded in a code block.
Project Index Summarizes key modules of the project, which are also used as context for downstreamprompts.toml.

Getting Started Guides Dependencies and system requirements are extracted from the codebase during preprocessing. Theparsers handle most of the heavy lifting here.
Installation, Usage, & Testing Setup instructions and usage guides are automatically created based on data extracted from the codebase.

Community & Support Development roadmap, contribution guidelines, license information, and community resources. Areturn button is also included for easy navigation.
Contribution Guides Instructions for contributing to the project, including resource links and a basic contribution guide. Graph of contributors is also included for open-source projects.

ReadmeAI requires Python 3.9 or higher, and one of the following installation methods:

To generate a README file, provide the source repository. ReadmeAI supports these platforms:

ReadmeAI is model agnostic, with support for the following LLM API services:

ReadmeAI is available onPyPI as readmeai and can be installed as follows:

Install with pip (recommended for most users):

❯ pip install -U readmeai

Withpipx, readmeai will be installed in an isolated environment:

❯ pipx install readmeai

The fastest way to install readmeai is withuv:

❯ uv tool install readmeai

To runreadmeai in a containerized environment, pull the latest image from [Docker Hub][dockerhub-link]:

❯ docker pull zeroxeli/readme-ai:latest

When runningreadmeai with a third-party service, you must provide a valid API key. For example, theOpenAI client is set as follows:

❯export OPENAI_API_KEY=<your_api_key># For Windows users:❯set OPENAI_API_KEY=<your_api_key>

Below is the minimal command required to runreadmeai using theOpenAI client:

❯ readmeai --api openai -o readmeai-openai.md -r https://github.com/eli64s/readme-ai

ReadmeAI can easily switch between API providers and models. We can run the same command as above with theAnthropic client:

❯ readmeai --api anthropic -m claude-3-5-sonnet-20240620 -o readmeai-anthropic.md -r https://github.com/eli64s/readme-ai

And finally, with theGoogle Gemini client:

❯ readmeai --api gemini -m gemini-1.5-flash -o readmeai-gemini.md -r https://github.com/eli64s/readme-ai

We can also runreadmeai with free and open-source locally hosted models using the Ollama:

❯ readmeai --api ollama --model llama3.2 -r https://github.com/eli64s/readme-ai

To generate a README file from a local codebase, simply provide the full path to the project:

❯ readmeai --repository /users/username/projects/myproject --api openai

Adding more customization options:

❯ readmeai --repository https://github.com/eli64s/readme-ai \           --output readmeai.md \           --api openai \           --model gpt-4 \           --badge-color A931EC \           --badge-style flat-square \           --header-style compact \           --navigation-style fold \           --temperature 0.9 \           --tree-depth 2           --logo LLM \           --emojis solar

ReadmeAI supportsoffline mode, allowing you to generate README files without using a LLM API service.

❯ readmeai --api offline -o readmeai-offline.md -r https://github.com/eli64s/readme-ai

Run thereadmeai CLI in a Docker container:

❯ docker run -it --rm \    -e OPENAI_API_KEY=$OPENAI_API_KEY \    -v"$(pwd)":/app zeroxeli/readme-ai:latest \    --repository https://github.com/eli64s/readme-ai \    --api openai

Try readme-ai directly in your browser on Streamlit Cloud, no installation required.

See thereadme-ai-streamlit repository on GitHub for more details about the application.

Thepytest andnox frameworks are used for development and testing.

Install the dependencies with uv:

❯ uv pip install --dev --grouptest --all-extras

Run the unit test suite using Pytest:

❯ maketest

Using nox, test the app against Python versions3.9,3.10,3.11, and3.12:

❯ make test-nox

Customize your README generation with a variety of options and style settings supported such as:

Run the following command to view all available options:

❯ readmeai --help

This gallery showcases a diverse collection of README examples generated across various programming languages, frameworks, and project types.

We invite developers to share their generated README files in ourShow & Tell discussion category. Your contributions help:

• Showcase diverse documentation styles
• Provide real-world examples
• Help improve the ReadmeAI tool

Find additional README examples in ourexamples directory on GitHub.

• Releasereadmeai 1.0.0 with robust documentation creation and maintenance capabilities.
• Extend template support for variousproject types andprogramming languages.
• DevelopVscode Extension to generate README files directly in the editor.
• DevelopGitHub Actions to automate documentation updates.
• Addbadge packs to provide additional badge styles and options.
  • Code coverage, CI/CD status, project version, and more.

Contributions are welcome! Please read theContributing Guide to get started.

• 💡Contributing Guide: Learn about our contribution process and coding standards.
• 🐛Report an Issue: Found a bug? Let us know!
• 💬Start a Discussion: Have ideas or suggestions? We'd love to hear from you.

A big shoutout to the projects below for their awesome work and open-source contributions:

Copyright © 2023-2025readme-ai.
Released under theMIT license.