README Wizard

AI-powered README generator that scans your codebase and creates comprehensive documentation using Claude.

Features

• Intelligent Codebase Scanning — discovers and analyses project structure
• Source-First Ranking — manifests, then real source code, then config, then docs, so src/ never gets crowded out by root-level config files
• Transparent Truncation — every file that did not reach the model is listed, with the reason
• Smart Content Filtering — excludes binaries, build artifacts, and secrets
• Gitignore Integration — honours the root .gitignore and every nested one
• Truncation Detection — a README cut off by the output cap is retried at a higher limit, then loudly flagged (and the process exits non-zero) rather than reported as a success
• Bounded Retry — 429 / 5xx / connection errors retry with exponential backoff and jitter, honouring retry-after
• Multiple Output Options — write a file or preview with --dry-run
• Configurable Limits — control max files and lines to stay within token limits
• Project Tree Generation — visual directory structure in the output

Prerequisites

• Node.js 20 or higher (required by commander@14 and ora@9)
• An Anthropic API key

Installation

Install globally via npm:

npm install -g @sidhxntt/readme-wizard

Or run directly with npx:

npx @sidhxntt/readme-wizard generate

Configuration

Set your Anthropic API key as an environment variable:

export ANTHROPIC_API_KEY=your-api-key-here

The scan command needs no API key — it is entirely local and free.

Usage

# Generate a README for the current directory
readme-wizard generate

# Generate for a specific directory
readme-wizard generate /path/to/project

# Preview without writing a file
readme-wizard generate --dry-run

# Custom output location (relative to the target directory)
readme-wizard generate -o DOCUMENTATION.md

# Scan only — see exactly what would be sent to the model, spend nothing
readme-wizard scan

CLI Reference

generate [dir] (alias: gen)

Scans the project and asks Claude to write a README.

| Option | Description | Default | |---|---|---| | -o, --output <file> | Output file path, relative to the target directory | README.md | | -m, --model <model> | Claude model to use | claude-sonnet-5 | | --max-files <n> | Maximum files to include in context | 80 | | --max-lines <n> | Maximum lines per file (priority files get 3×) | 150 | | --no-tree | Skip project tree generation | — | | --dry-run | Print the README to stdout instead of writing | — | | --overwrite | Overwrite an existing README without asking | — |

Without --overwrite, an existing output file triggers a confirmation prompt. In a non-TTY environment (CI) the run aborts with a clear message instead of hanging.

--max-files and --max-lines reject non-numeric input — --max-files abc is an error, not a silent scan of zero files.

scan [dir]

Scan the project and print the tree, the file count, and the context size — no API call.

| Option | Description | Default | |---|---|---| | --max-files <n> | Maximum files to include | 80 | | --max-lines <n> | Maximum lines per file | 150 |

Project Structure

readme_wizard/
├── src/
│   ├── index.js      # CLI entry point and command definitions
│   ├── scanner.js    # Codebase scanning, ranking, and gitignore handling
│   └── generator.js  # Anthropic API integration and prompt construction
└── package.json

Key Files

• src/index.js — Commander-based CLI with Chalk/Ora output, option validation, and the truncation warning
• src/scanner.js — builds the project tree, honours nested .gitignore files, ranks and caps the file set, and reports what was dropped
• src/generator.js — lazily constructs the Anthropic client, builds the prompt, and handles retries, output-cap retries, and the prompt-size guard

How It Works

1. Scan phase — walks the project directory, filtering on:

   • .gitignore patterns (root and nested) plus built-in exclusions
   • a file-extension allowlist
   • a selection ranking: manifests → source code → config → docs
   • a character budget, so an oversized prompt never reaches the API

2. Context building — assembles the project name, full file listing, directory tree, and key file contents.

3. AI generation — sends the context to Claude with instructions to detect the project type, use real code examples, and emit clean Markdown. Transient API failures retry with backoff; a truncated answer is retried once at a higher output cap.

Contributing

1. Clone the repository
2. Install dependencies: npm install
3. Run in development mode: npm run dev
4. Test against real projects with readme-wizard scan (free) before spending an API call
5. Submit a pull request

Key dependencies: @anthropic-ai/sdk, commander, chalk, ora, glob, ignore.

License

MIT