ReadmeAI is a developer tool that uses a repository processing engine and advanced language models to automatically generate README files. Simply provide the URL or path of a codebase, and it can generate a well-structured and detailed README. It is designed to simplify the process of creating and maintaining documentation across all technical domains and for users of different experience levels.
Core principles and uses:
- Automation: Generate detailed and structured README files with a single command.
- Customizable: Choose from multiple templates, styles, badges, and other options.
- Flexibility: Switch between OpenAI, Ollama, Anthropic, and Gemini at any time.
- Language-agnostic: Compatible with multiple languages and frameworks.
- Best practices: Ensure clean and consistent documentation for all projects.
- Smart filtering: Perform intelligent file analysis through customizable .readmeaiignore patterns.
- Offline mode: Create README files offline without using an LLM API service.
The generated content sections include: project introduction (capturing the essence and value proposition of the project), detailed feature breakdown and technical capabilities, project structure (a directory tree generated in pure Python embedded in a code block, with key modules summarized as context for subsequent prompts, with the file as .toml), quick start guide (dependencies and system requirements are extracted from the codebase during preprocessing, with the main processing done by the parser), installation/usage/testing (automatically created based on data extracted from the codebase), community and support (development roadmap, contribution guidelines, license information, community resources, and includes a back button), contribution guidelines (including resource links and basic contribution guidelines; open source projects will also include a contributors chart).
Installation requirements: Python 3.10 or higher is required. Multiple installation methods are supported:
- Install with pip (recommended for most users): pip install readmeai
- Install with pipx (installs in an isolated environment): pipx install readmeai
- Install with uv (fastest): uv pip install readmeai
- With Docker: Pull the latest image from Docker Hub and run the container.
- Install from source: git clone https://github.com/eli64s/readme-ai cd readme-ai pip install -r setup/requirements.txt Or run the installation script: bash setup/setup.sh Or install with poetry: poetry install
Optional dependencies (for the Anthropic and Google Gemini clients):
- Anthropic: pip install "readmeai[anthropic]"
- Google Gemini: pip install "readmeai[google-generativeai]"
- Install multiple at the same time: pip install "readmeai[anthropic,google-generativeai]"
Usage: A valid API key must be provided when using third-party services. For example, the OpenAI client requires an API key to be set. To run Ollama, you must first pull the model and start the server: ollama pull llama3.2:latest export OLLAMA_HOST=127.0.0.1 && ollama serve Anthropic requires exporting the API key: export ANTHROPIC_API_KEY=<your_api_key> Google Gemini requires exporting: export GOOGLE_API_KEY=<your_api_key>
Minimal command example to run with the OpenAI client: readmeai --repository https://github.com/eli64s/readme-ai --api openai The default model is gpt-3.5-turbo; when using gpt-4 and higher series models, be careful to monitor costs. Switch to the Anthropic client: readmeai --repository https://github.com/eli64s/readme-ai --api anthropic Switch to the Google Gemini client: readmeai --repository https://github.com/eli64s/readme-ai --api gemini Use a local Ollama model: readmeai --repository https://github.com/eli64s/readme-ai --api ollama Generate a README from a local codebase; just provide the full project path. More customization options can be added. Supports offline mode, with no LLM API service required. The CLI can also be run in a Docker container. You can try it directly in the browser on Streamlit Cloud (no installation required), but the web app may not always be in sync with the latest features; it is recommended to use the CLI to get the latest features.
Running after installing from source:
- If installed with a bash script, first activate the virtual environment: conda activate readmeai, then run: python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai
- If using poetry: poetry shell, then run: poetry run python3 -m readmeai.cli.main -r https://github.com/eli64s/readme-ai
Development and testing use the pytest and nox frameworks. Use uv to install dependencies and pytest to run unit tests; use nox to test the application on Python 3.10, 3.11, 3.12, and 3.13.
View all available options: run readmeai --help.
The official documentation provides a complete configuration and customization guide. The project also provides an example gallery showing README examples generated for various programming languages, frameworks, and project types.
The project roadmap includes: releasing readmeai 1.0.0; expanding template support for various project types and programming languages; developing a VSCode extension to generate READMEs directly in the editor; developing GitHub Actions to automatically update documentation; adding a badge package to provide more badge styles and options (code coverage, CI/CD status, project version, etc.).
License: MIT license. Copyright © 2023-2025 readme-ai.
