Refer to the Ollama documentation for more information on setting up the Ollama server.

To start, follow these steps:

1. Pull your model of choice from the Ollama repository:

   ❯ ollama pull llama3.2:latest
   

2. Start the Ollama server and set the OLLAMA_HOST environment variable:

   ❯ export OLLAMA_HOST=127.0.0.1 && ollama serve
   

1. Export your Anthropic API key:

   ❯ export ANTHROPIC_API_KEY=
   

1. Export your Google Gemini API key:

   ❯ export GOOGLE_API_KEY=
   </details>
   

Using the CLI

Running with a LLM API service

Below is the minimal command required to run readmeai using the OpenAI client:

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

[!IMPORTANT] The default model set is gpt-3.5-turbo, offering the best balance between cost and performance.When using any model from the gpt-4 series and up, please monitor your costs and usage to avoid unexpected charges.

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

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

And finally, with the Google Gemini client:

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

Running with local models

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

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

Running on a local codebase

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

Running in offline mode

ReadmeAI supports offline 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

 Docker

Run the readmeai 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

 Streamlit

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

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

[!WARNING] The readme-ai Streamlit web app may not always be up-to-date with the latest features. Please use the command-line interface (CLI) for the most recent functionality.

 From source

Testing

The pytest and nox frameworks are used for development and testing.

Install the dependencies with uv:

❯ uv pip install --dev --group test --all-extras

Run the unit test suite using Pytest:

❯ make test

Using nox, test the app against Python versions 3.10, 3.11, 3.12, and 3.13:

❯ make test-nox

[!TIP] _{Nox is an automation tool for testing applications in multiple environments. This helps ensure your project is compatible with across Python versions and environments.}

Configuration

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

Example Gallery

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

Community Contribution

Share Your README Files

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

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

Find additional README examples in our examples directory on GitHub.

Roadmap

• Release readmeai 1.0.0 with robust documentation creation and maintenance capabilities.
• Extend template support for various project types and programming languages.
• Develop Vscode Extension to generate README files directly in the editor.
• Develop GitHub Actions to automate documentation updates.
• Add badge packs to provide additional badge styles and options.
  • Code coverage, CI/CD status, project version, and more.

Contributing

Contributions are welcome! Please read the Contributing 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.

Acknowledgments

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

🎗 License

Copyright © 2023-2025 readme-ai.
Released under the MIT license.