readme-ai

Instantly generate beautiful, professional READMEs from any codebase — powered by Claude.

readme-ai scans your repository, understands its structure, languages, and intent, then asks Claude to write a polished README — streamed live to your terminal.

---

Features

• Zero configuration — point it at any repo, get a README in seconds
• Smart context extraction — reads source files, package metadata, directory structure, CI config, Dockerfile, and more
• Three writing styles — standard, minimal, detailed
• Live streaming output — see the README being written in real time
• Cross-language — works with Python, Node/TypeScript, Go, Rust, Ruby, Java, and more
• Respects existing README — feeds it as context so the rewrite is coherent
• Dry-run mode — preview without touching any file

---

Installation

pip install readme-ai

Or install from source:

git clone https://github.com/Lethe044/readme-ai.git
cd readme-ai
pip install -e .

---

Quick Start

export ANTHROPIC_API_KEY="sk-ant-..."

# Generate README for the current directory
readme-ai

# Or target a specific project
readme-ai --path ./my-project

That's it. A README.md will be written (or overwritten after confirmation) in the repository root.

---

Usage

usage: readme-ai [-h] [--path PATH] [--output FILE] [--style {standard,minimal,detailed}]
                 [--api-key KEY] [--model MODEL] [--no-stream] [--dry-run] [--overwrite] [--version]

Flag	Default	Description
--path, -p	.	Path to the repository root
--output, -o	README.md	Output filename
--style, -s	standard	Writing style: standard | minimal | detailed
--api-key, -k	$ANTHROPIC_API_KEY	Anthropic API key
--model, -m	claude-sonnet-4-6	Claude model to use
--no-stream	—	Disable streaming; wait for full response
--dry-run	—	Print to stdout only, don't write to disk
--overwrite, -y	—	Skip the overwrite confirmation prompt

Examples

# Minimal README for a small library
readme-ai --style minimal

# Exhaustive documentation for a complex project
readme-ai --style detailed --output DOCS.md

# Preview without writing anything
readme-ai --dry-run

# Use a specific model
readme-ai --model claude-opus-4-6

---

Configuration

readme-ai reads your ANTHROPIC_API_KEY from the environment. The cleanest way to set it permanently:

# ~/.bashrc or ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-..."

No config file needed. All options are available via CLI flags.

---

How It Works

Your Repo
    │
    ▼
analyzer.py          ← walks files, extracts structure, metadata, signals
    │
    ▼
generator.py         ← builds a rich prompt, calls Claude API (streaming)
    │
    ▼
README.md            ← written to your repo root

The analyzer collects:

• Directory tree (up to 3 levels deep)
• Source file contents (top-priority files first, truncated intelligently)
• Package metadata (package.json, pyproject.toml, Cargo.toml, go.mod, …)
• Signals — has tests? Docker? CI? License?
• Existing README — used as context for the rewrite

All of this is assembled into a structured prompt and sent to Claude, which streams the Markdown response directly to your terminal.

---

Development

git clone https://github.com/Lethe044/readme-ai.git
cd readme-ai
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check .

# Type check
mypy readme_ai

---

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you'd like to change.

1. Fork the repo
2. Create your branch: git checkout -b feat/my-feature
3. Commit your changes: git commit -m 'feat: add my feature'
4. Push: git push origin feat/my-feature
5. Open a Pull Request

---

License

MIT © Lethe044