ReadmeAI - AI-Powered README Generator
Automatically generate structured, customizable README files using AI, with support for multiple LLM providers and offline mode.
- Source repo
- eli64s/readme-ai
- Stars
- ★ 3k
- Last updated
- 2mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 51/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers who want to quickly generate a professional README for their GitHub repository without manual writing.
- Not a fit if
- Teams unwilling to send codebase content to third-party LLM APIs
- Teams needing mature GitLab or Bitbucket support
- Source review
- 51/100 · Major gaps 2 safety controls not found
What does this agent do, and when should you use it?
ReadmeAI is a command-line tool that leverages advanced language models to automatically generate README files. It parses a codebase, extracting dependencies, structure, and tech stack, then produces a comprehensive document with sections like project overview, features table, directory tree, getting started guide, and more. It supports various header and navigation styles, customizable badge colors, styles, and logos. Multiple LLM backends are available: OpenAI, Anthropic, Gemini, Ollama, and an offline mode requiring no API key. The project is Python-based, distributed as a PyPI package, and can be run via Docker. It aims to streamline documentation creation and maintenance, ensuring consistent and readable project documentation.
ReadmeAI accepts a repository URL or local path as input, fetching source code via the file system or Git hosting platforms. Internally, a preprocessor parses the code, extracting project structure, dependencies, and key modules (via readmeai.parsers and tree.py). It then calls the configured LLM API (e.g., OpenAI gpt-3.5-turbo) or uses offline mode, generating README content based on templates in prompts.toml. The output includes sections such as project introduction, features table, directory structure, installation guide, usage instructions, and contribution guidelines. The CLI provides options like --repository, --api, --model, --badge-style, --header-style, allowing extensive customization. Output is saved as a Markdown file, specified via --output. Additionally, it supports file filtering via .readmeaiignore patterns.
- Developers who want to quickly generate a professional README for their GitHub repository without manual writing.
- Teams needing consistent documentation style and structure across multiple projects.
- Technical writers aiming to generate accurate docs based on real code to save time.
- Project maintainers who want to automate documentation updates as the codebase evolves (via future GitHub Action integration).
- Users who operate in offline environments or prefer not to use external APIs can generate basic READMEs.
- Professionals who switch between LLM providers based on task requirements, choosing OpenAI, Anthropic, or local Ollama models.
How do you install or deploy this agent?
First, ensure Python 3.9 or higher. The recommended installation is via pip: pip install -U readmeai. Alternatively, use pipx (pipx install readmeai), uv (uv tool install readmeai), or Docker (docker pull zeroxeli/readme-ai:latest). For using Anthropic or Gemini clients, install extra dependencies: pip install "readmeai[anthropic]" or pip install "readmeai[google-generativeai]".
How do you use this agent?
After installation, ensure you set the API key (e.g., export OPENAI_API_KEY=<your_key>). Run the following command to generate a README: readmeai --api openai -o README.md -r https://github.com/eli64s/readme-ai. For Anthropic: readmeai --api anthropic -m claude-3-5-sonnet-20240620 -o README.md -r <repo>. For Gemini: readmeai --api gemini -m gemini-1.5-flash -o README.md -r <repo>. For Ollama: first pull a model (ollama pull llama3.2), then run readmeai --api ollama --model llama3.2 -r <repo>. For a local codebase, provide a path: readmeai --repository /path/to/project --api openai. Offline mode: readmeai --api offline -o README.md -r <repo>. To view all options, run readmeai --help.
What are this agent's strengths and limitations?
- Supports multiple LLM providers (OpenAI, Anthropic, Gemini, Ollama), providing flexibility and model choice freedom.
- Highly customizable: multiple header styles (classic, modern, compact, banner, console), badge colors and styles, and navigation styles.
- Offers an offline mode, allowing README generation without an API key, preserving privacy and saving costs.
- Language agnostic, supporting a wide range of programming languages and frameworks by automatically extracting project information via parsers.
- Provides smart file filtering (
.readmeaiignore) to avoid including unnecessary files. - Can be built from source and run via Docker, catering to different installation preferences.
- Using third-party LLM APIs may incur costs, requires API keys, and users may need to monitor usage (default model gpt-3.5-turbo is cost-effective, but advanced models can be expensive).
- Generated README quality depends on LLM output and may not always be accurate, especially for very complex or domain-specific codebases.
- Requires Python 3.9+ environment, and installation may involve extra dependencies (e.g., anthropic and google-generativeai extras).
- Offline mode READMEs may lack detail or context because there is no LLM to generate dynamic content.
- Support for GitLab and Bitbucket is not fully explicit and may be less mature than GitHub integration.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| ReadmeAI - AI-Powered README Generator This agent | 51 · Major gaps | CLIFree + model costs | ★ 3k | 2mo ago | Python | OpenAI API · Claude API |
| Webwright Browser Coding Agent | 66 · Some gaps | CLIFree + model costs | ★ 6.1k | 13d ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| mlx-serve: Native LLM Inference for Apple Silicon | 48 · Major gaps | Desktop appFree | ★ 2k | today | Zig | Claude Code · OpenAI API · Claude API |
| Giselle | 43 · Major gaps | Self-hosted serviceFreemium | ★ 558 | 1mo ago | TypeScript | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: CLI requires user-provided API keys, but least privilege is not explicitly addressed; offline mode exists, but no user confirmation step is mentioned; data flow transparency is partial, README mentions data sent to LLM APIs but not detailed; sensitive data handling: API keys passed via environment variables, but storage not specified; dependency security: some versions pinned, but no security audit mentioned; external effects: generates README files, but no impact on system; rollback: not mentioned; source attribution: author info present, but not verified. Deductions: lack of user confirmation, rollback, and insufficient detail on data flow and sensitive data handling.
Evidence shows: README and pyproject.toml descriptions are consistent; dependencies listed, but availability not verified; failure messages: tests cover error handling, but user-friendly messages not detailed. Deductions: dependency availability not verified, failure messages not detailed.
Evidence shows: README provides multiple usage scenarios (local, GitHub, GitLab, Bitbucket), supports multiple LLM providers and offline mode; capability boundaries defined via CLI options; trigger precision via CLI parameters; environment fit supports Python 3.9+ and multiple installation methods. Deductions: capability boundaries not explicitly stated, but overall adequate.
Evidence shows: information architecture clear with quick links and TOC; install notes detailed for pip, pipx, uv, docker; naming stable, CLI commands consistent; examples and FAQ rich, but FAQ not separate; known limitations not stated; license MIT; versioning/changelog not provided; maintenance responsibility has author info. Deductions: missing known limitations and versioning/changelog.
Evidence shows: output is README file, directly usable; marginal value high, automates documentation; cost-benefit: offline mode available, but API usage may incur costs. Deductions: cost-benefit not detailed, but overall reasonable.
Evidence shows: README feature claims correspond to code and tests; cross-source corroboration limited, but tests and docs consistent; fact-inference separation: README distinguishes feature descriptions and examples. Deductions: cross-source corroboration insufficient.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- API keys are passed via environment variables, but storage and rotation mechanisms are not specified; users should manage them carefully.
- Dependency versions are partially pinned, but no security audit is mentioned; users should regularly check for vulnerabilities.
- Generating README may send code content to third-party LLM APIs; users should be aware of data privacy risks.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
✨ Features - refactor: Reduce complexity of markdown table generator methods. @eli64s (#70) - enhancement: Add more context to LLM prompts. @eli64s (#69) - feat: Add CLI option --emojis to change README header prefixes @eli64s (#67) 🪲 Bug Fixes - fix: #35 Update tokenization logic causing issues for larger codebases @eli64s (#68) - fix #65: Update dependency parser method for build.gradle files @eli64s (#66) 📄 Documentation - docs: Update readmeai demo videos. @eli64s (#71) ⚙️ Dependency Updates - Bump urllib3 from 2.0.6 to 2.0.7 @dependabot (#64) ---View on GitHub ↗ -
Release notes excerpt
What's Changed 🚀 Features - feat: Add support for three badge icon styles. @eli64s (#62) - feat: Add README file in German [README-de](https://github.com/eli64s/readme-ai/blob/main/docs/README-de.md) and update other README files (FR, zh-CN). 🧩 Dependency Updates - Bump urllib3 from 2.0.5 to 2.0.6 @dependabot (#60)View on GitHub ↗ -
Release notes excerpt
What's Changed 🚀 Features - Add new SVG badge icons that user's can select using the CLI option --badges @eli64s (#58) - Refactor readmeai package structure to improve organization and readability @eli64s (#58)View on GitHub ↗