readme-ai

The #1 AI-Powered README Generator for Developers

Generate stunning, production-quality READMEs from any codebase in seconds — powered by Claude, GPT-4o, Gemini, or Ollama

One command. Zero install. Beautiful READMEs.

npx @malikasadjaved/readme-ai

Quick Start · Themes · AI Providers · Plugins · CLI Options · GitHub Action · Contributing

Overview

readme-ai is the most powerful open-source AI README generator available. It reads your actual source code — not just directory names — and generates a complete, polished README with architecture diagrams, badges, install instructions, usage examples, and API docs.

Point it at any local project or public GitHub repo and get a production-ready README in seconds.

Why readme-ai?

• Deep code analysis — parses actual source files, not just file trees
• 10+ languages supported — Node.js, Python, Rust, Go, Java (Gradle/Maven), Ruby, Swift, Dart/Flutter, and more
• Mermaid architecture diagrams — auto-generated from your code structure
• Plugin system — extend with custom analyzers and themes
• Works with any AI — Claude, GPT-4o, Gemini, or fully local with Ollama (free)
• 186 tests passing — battle-tested and reliable

Key Features

| Feature | Description | |---------|-------------| | Zero Install | npx @malikasadjaved/readme-ai — works instantly, no setup | | Deep Code Analysis | Extracts functions, API endpoints, CLI commands, exports | | Auto Mermaid Diagrams | Architecture diagrams generated from code structure | | 5 Themes | Default, Modern, Hacker, Minimal, Academic | | 4 AI Providers | Claude, GPT-4o, Gemini Flash, Ollama (local/free) | | Smart Badges | Auto-detects language, frameworks, CI, Docker, license | | GitHub URL Support | Analyze any public repo: github:user/repo | | GitHub Action | Auto-regenerate README on every push | | Plugin System | Custom analyzers and themes via plugins | | 10+ Languages | Node.js, Python, Rust, Go, Java, Ruby, Swift, Dart, and more | | Project Config | .readmeairc.json or readme-ai.config.js | | API Docs | Auto-generated from exported functions and classes |

Quick Start

# Generate README for current directory
npx @malikasadjaved/readme-ai

# Point at a local project
npx @malikasadjaved/readme-ai ./my-project

# Point at a GitHub repo
npx @malikasadjaved/readme-ai github:expressjs/express

# Interactive mode (guided prompts)
npx @malikasadjaved/readme-ai --interactive

Install globally (optional)

npm install -g @malikasadjaved/readme-ai
readme-ai ./my-project

Demo

Comparison

| Feature | readme-ai | eli64s/readme-ai | readmeX | |---------|:---------:|:----------------:|:-------:| | npx support (zero install) | Yes | No | No | | Mermaid architecture diagrams | Yes | No | No | | Plugin system | Yes | No | No | | GitHub URL analysis | Yes | Yes | Yes | | Multiple themes | 5 | 3 | No | | GitHub Action template | Yes | No | No | | API docs from code | Yes | No | No | | Badge auto-generation | Yes | Yes | Partial | | Local AI (Ollama) | Yes | No | No | | 10+ language support | Yes | Partial | No | | Pre-commit hooks | Yes | No | No |

Themes

Default — Clean & Professional

The standard theme with a centered header, emoji section headers, and shields.io badges.

Modern — Emoji-rich & Colorful

Heavy use of emojis, colorful badge rows, and visual separators for maximum impact.

Hacker — Terminal Aesthetic

ASCII art header, monospace styling, > prefixed descriptions — for the terminal lovers.

Minimal — Pure Markdown

No emojis, no badges, no frills. Just clean, readable markdown.

Academic — Formal & Structured

Numbered sections, citation-style references, formal language. Great for research projects.

# Use a specific theme
npx @malikasadjaved/readme-ai --theme modern
npx @malikasadjaved/readme-ai --theme hacker
npx @malikasadjaved/readme-ai --theme minimal
npx @malikasadjaved/readme-ai --theme academic

Want a custom theme? Use the plugin system to create your own!

AI Providers

Claude (Anthropic) — Default

export ANTHROPIC_API_KEY=sk-ant-...
npx @malikasadjaved/readme-ai

GPT-4o-mini (OpenAI)

export OPENAI_API_KEY=sk-...
npx @malikasadjaved/readme-ai --provider openai

Gemini Flash (Google)

export GEMINI_API_KEY=...
npx @malikasadjaved/readme-ai --provider gemini

Ollama (Local, Free, Private)

# Make sure Ollama is running locally
npx @malikasadjaved/readme-ai --provider ollama
npx @malikasadjaved/readme-ai --provider ollama --model llama3.1

CLI Options

Usage: readme-ai [repo] [options]

Arguments:
  repo                     Local path or GitHub URL (github:user/repo)

Options:
  -V, --version            Output the version number
  -o, --output <file>      Output file path (default: "README.md")
  -p, --provider <name>    AI provider: anthropic | openai | gemini | ollama (default: "anthropic")
  -m, --model <name>       Model name (depends on provider)
  -t, --theme <name>       Theme: default | minimal | hacker | modern | academic (default: "default")
  --no-diagram             Skip Mermaid architecture diagram
  --no-badges              Skip badge generation
  --no-api-docs            Skip API documentation section
  --interactive            Run in interactive mode
  --action                 Generate a GitHub Action for auto-updating README
  --overwrite              Overwrite existing README without asking
  --dry-run                Print README to stdout instead of writing to file
  -h, --help               Display help for command

Examples

# Generate with Modern theme using OpenAI
npx @malikasadjaved/readme-ai ./my-app --provider openai --theme modern

# Dry run (preview without writing)
npx @malikasadjaved/readme-ai --dry-run

# Generate without diagram and badges
npx @malikasadjaved/readme-ai --no-diagram --no-badges

# Overwrite existing README and generate GitHub Action
npx @malikasadjaved/readme-ai --overwrite --action

# Analyze a remote GitHub repository
npx @malikasadjaved/readme-ai github:tiangolo/fastapi --theme academic

Plugins

readme-ai supports a plugin system for custom analyzers and themes. Plugins can add extra README sections, badges, or entirely new visual themes.

// readme-ai.config.js
export default {
  plugins: [
    './my-local-plugin.js',       // local plugin file
    'readme-ai-plugin-example',   // npm package
  ],
};

Packages named readme-ai-plugin-* in node_modules are auto-discovered. See CONTRIBUTING.md for the full plugin authoring guide.

Plugin Example

const myPlugin = {
  name: 'my-plugin',
  analyzers: [{
    name: 'security-scanner',
    analyze: async ({ scan, codeAnalysis, deps }) => ({
      sections: { 'Security': 'No vulnerabilities found.' },
      badges: [{ label: 'security', message: 'passing', color: 'green' }],
    }),
  }],
  themes: [{
    name: 'corporate',
    render: (data) => `# ${data.projectName}\n\n${data.description}`,
  }],
};
export default myPlugin;

GitHub Action

Auto-regenerate your README on every push to main:

# Generate the action file automatically
npx @malikasadjaved/readme-ai --action

Or manually create .github/workflows/readme-update.yml:

name: Update README

on:
  push:
    branches: [main, master]
    paths-ignore:
      - 'README.md'

jobs:
  update-readme:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Generate README
        run: npx @malikasadjaved/readme-ai@latest --overwrite --no-interactive
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Commit updated README
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: 'docs: auto-update README [skip ci]'
          file_pattern: README.md

Supported Languages

| Language | Package Manager | Install | Build | Test | |----------|----------------|---------|-------|------| | Node.js | npm / yarn / pnpm | npm install | npm run build | npm test | | Python | pip / pyproject | pip install -r requirements.txt | — | pytest | | Rust | cargo | cargo build --release | cargo build | cargo test | | Go | go modules | go mod download | go build | go test ./... | | Java (Gradle) | gradle | gradle build | gradle build | gradle test | | Java (Maven) | maven | mvn install | mvn package | mvn test | | Ruby | bundler | bundle install | — | bundle exec rspec | | Swift | Swift PM | swift package resolve | swift build | swift test | | Dart/Flutter | pub | dart pub get | dart compile | dart test |

Architecture

graph TD
  A[CLI Input] --> B[Command Parser]
  B --> C[Repo Fetcher]
  C -->|Local Path| D[File Scanner]
  C -->|GitHub URL| E[GitHub API]
  E --> D
  D --> F[Code Analyzer]
  D --> G[Dependency Analyzer]
  F --> H[AI Provider]
  G --> H
  H --> I[Section Generators]
  I --> J[Theme Engine]
  J --> K[Plugin System]
  K --> L[Markdown Writer]
  L --> M[README.md]

Project Structure

readme-ai/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── cli.ts                # Interactive mode
│   ├── config.ts             # Configuration management
│   ├── commands/
│   │   └── generate.ts       # Main generation pipeline
│   ├── analyzers/
│   │   ├── repo-fetcher.ts   # Fetch from local or GitHub
│   │   ├── file-scanner.ts   # Scan and categorize files
│   │   ├── code-analyzer.ts  # Extract functions, endpoints, exports
│   │   ├── dependency-analyzer.ts  # 10+ language support
│   │   ├── badge-generator.ts
│   │   └── diagram-builder.ts
│   ├── generators/
│   │   ├── overview.ts       # Project summary + features
│   │   ├── install.ts        # Install instructions
│   │   ├── usage.ts          # Usage examples + API docs
│   │   ├── contributing.ts   # Contributing guide
│   │   └── changelog.ts      # Changelog section
│   ├── plugins/
│   │   └── index.ts          # Plugin loader and registry
│   ├── providers/
│   │   ├── anthropic.ts      # Claude
│   │   ├── openai.ts         # GPT-4o
│   │   ├── gemini.ts         # Gemini Flash
│   │   └── ollama.ts         # Local Ollama
│   ├── themes/
│   │   ├── default.ts
│   │   ├── modern.ts
│   │   ├── hacker.ts
│   │   ├── minimal.ts
│   │   └── academic.ts
│   └── utils/
│       ├── file-utils.ts
│       ├── github-api.ts
│       ├── language-detector.ts
│       ├── markdown-writer.ts
│       ├── template-engine.ts
│       └── cache.ts
├── tests/                    # 186 tests (Vitest)
├── CONTRIBUTING.md           # Full contributor guide
├── CHANGELOG.md
└── LICENSE

Contributing

Contributions are welcome! See CONTRIBUTING.md for the full guide.

git clone https://github.com/malikasadjaved/readme-ai.git
cd readme-ai
npm install
npm test        # 186 tests
npm run dev     # development mode

Pre-commit hooks with Husky + lint-staged ensure code quality on every commit.

Star History

If you find readme-ai useful, please give it a star! It helps others discover the project.

License

MIT — use it freely in personal and commercial projects.

Built by Malik Asad Javed

readme-ai — the best AI README generator for developers

readme generator | ai documentation | markdown generator | github readme | developer tools | claude | openai | gemini | ollama | mermaid diagrams | open source