🚀 Never Write a README.md from Scratch Again - Meet readmeai

Every developer has been there. You finally finish that side project, push it to GitHub, open the repo and the README.md is just # project-name. You tell yourself you'll fix it tomorrow. Tomorrow becomes next week. The repo quietly gathers dust.

The excuse is always the same: writing a good README is harder than it looks. You need a hero description, install instructions, usage examples, badges, a contributing guide, a license section and you have to make it not look like a templated ghost wrote it. It's not technical work; it's polishing work. And polishing work is the first thing that gets pushed aside when the next idea hits.

That's exactly why I built readmeai. It's a small Python CLI that scans your project structure, reads your key config files (pyproject.toml, package.json, Cargo.toml, go.mod, Dockerfile, …) and asks an LLM to generate a complete, badge-laden README.md ready to commit. One command, about ten seconds, and your repo stops looking orphaned. Local-first if you want it (Ollama works out of the box), zero heavy dependencies (requests is the only one), MIT-licensed, on PyPI today.

Quickstart in 90 Seconds

Install readmeai via pip:

pip install readmeai

Then run it in your project directory:

readmeai

That's it. Your README.md is generated and written to disk.

How It Works (Under the Hood)

1. readmeai scans your project directory for known configuration files and source code patterns.
2. It extracts metadata: project name, dependencies, language, build system, and file structure.
3. It sends this context to an LLM provider with a carefully crafted prompt.
4. The LLM returns a structured README, which readmeai writes to README.md.

The entire pipeline runs in about ten seconds for most projects.

Picking a Provider: OpenCode vs OpenAI vs Ollama

readmeai supports three LLM backends:

• OpenCode – Free, open-source model, no API key required. Best for quick experiments.
• OpenAI – Uses GPT-4 or GPT-3.5. Requires an API key. Produces the most polished output.
• Ollama – Run models locally on your machine. No data leaves your network. Works with any Ollama-compatible model.

Set the provider with the --provider flag:

readmeai --provider openai

Interactive Mode: Preview Before You Commit

Use the --interactive flag to review the generated README before it's written:

readmeai --interactive

This opens a diff view showing the proposed changes. You can accept, edit, or reject the output.

Supported Project Types & Config Files

readmeai automatically detects the following project types and their config files:

• Python: pyproject.toml, setup.py, setup.cfg, requirements.txt
• Node.js: package.json
• Rust: Cargo.toml
• Go: go.mod
• Docker: Dockerfile
• Java/Kotlin: pom.xml, build.gradle
• Ruby: Gemfile
• PHP: composer.json
• .NET: *.csproj

If your project type isn't listed, readmeai falls back to a generic analysis of your file structure.

Customising the Output

You can control the tone, length, and sections of the generated README:

readmeai --style concise
readmeai --style detailed
readmeai --sections install,usage,license

Available sections include: description, install, usage, badges, contributing, license, acknowledgements, and roadmap.

Roadmap & Contributing

Planned features:

• Support for monorepos with multiple packages
• Custom templates via YAML configuration
• GitHub Actions integration for auto-updating READMEs on push
• Support for more LLM providers (Anthropic, Gemini, Mistral)

Contributions are welcome. The project is MIT-licensed and hosted on GitHub. Open an issue or pull request for any feature requests or bug reports.

Closing Thoughts

A good README is the front door to your project. It tells people what your code does, why it matters, and how to use it. readmeai doesn't replace thoughtful documentation - it removes the friction of starting from a blank page. One command, ten seconds, and your repo stops looking orphaned.