✨ Features

• Understands your code — scans source files, package manifests, and directory structure; builds context before writing a single word
• Production-quality output — badges, installation instructions, real usage examples, configuration docs, contributing guide
• Smart prioritisation — reads pyproject.toml, package.json, main.py and similar files first so the AI leads with the most important context
• 15+ languages supported — Python, TypeScript, Go, Rust, Java, C/C++, Ruby, PHP, and more
• Dry-run mode — readme-ai scan shows exactly what the AI will see, with no API call
• Multilingual output — generate in English or Russian (--language ru)
• Non-destructive — always asks before overwriting an existing README

📦 Installation

pip install readme-ai

Or with pipx for an isolated global install:

pipx install readme-ai

Requirements: Python 3.9+ · An Anthropic API key

🚀 Usage

Generate a README

# Set your API key once
export ANTHROPIC_API_KEY="sk-ant-..."

# Generate README for the current directory
readme-ai generate .

# Or point at any project
readme-ai generate ~/projects/my-app

# Preview in terminal without writing to disk
readme-ai generate . --preview

# Generate in Russian
readme-ai generate . --language ru

# Write to a custom path
readme-ai generate . --output docs/README.md

Inspect what the AI sees (no API call)

readme-ai scan .

Output:

Project: my-app
Files found: 12
Languages detected:
  Python          ████████████ 6
  TypeScript      ██████ 3
  Shell           ██ 1

Priority files:
  ★ pyproject.toml
  ★ main.py
  ★ requirements.txt

Full options

readme-ai generate [OPTIONS] [PATH]

Arguments:
  PATH  Project directory [default: .]

Options:
  -o, --output PATH       Output file path [default: <path>/README.md]
  -k, --api-key TEXT      Anthropic API key (or set ANTHROPIC_API_KEY)
  -l, --language [en|ru]  Output language [default: en]
  -p, --preview           Print to stdout instead of writing to file
  -f, --overwrite         Skip the overwrite confirmation prompt
  -m, --model TEXT        Claude model to use
  -V, --version           Show version and exit

⚙️ Configuration

Get your key at console.anthropic.com.

The default model is claude-sonnet-4-20250514. You can override it with --model:

readme-ai generate . --model claude-opus-4-20250514

🔍 How it works

Your project
     │
     ▼
 📂 Scanner          Reads up to 30 files, prioritising entry points
     │               and package manifests. Builds a directory tree.
     ▼
 🧠 Prompt builder   Assembles structured context: tree, languages,
     │               package metadata, key source files.
     ▼
 ✨ Claude AI        Generates a README following strict documentation
     │               best practices with real examples and badges.
     ▼
 📄 README.md

🤝 Contributing

Contributions are welcome! Here's how to get started:

git clone https://github.com/aaxnet/readme-ai
cd readme-ai
pip install -e ".[dev]"
pytest tests/ -v

Please open an issue before starting work on a large feature. PRs should include tests.

📄 License

MIT © 2026 readme-ai contributors