readme-gen

A CLI tool that generates comprehensive README.md files by analyzing your codebase using Claude AI.

• AI-Powered Analysis: Uses Claude AI via the Anthropic Agent SDK to explore and understand your codebase
• Smart Classification: Automatically detects repository type (CLI, library, web app, API service, monorepo, etc.)
• Profile-Based Generation: Generates READMEs tailored to your project type (user-first, library-first, ops-first)
• Monorepo Support: Handles multi-package workspaces with per-package documentation
• Anti-Hallucination: Strict evidence-based generation from manifest files and actual code

Install

Via npm

npm install -g @yarlson/readme-gen

Via Bun

bun install -g @yarlson/readme-gen

Quickstart

# Set your Anthropic API key
export ANTHROPIC_API_KEY="your-api-key"

# Generate a README for the current directory
readme-gen

Usage

Basic Usage

readme-gen

Analyzes the current directory and generates a README.md file.

With Additional Context

readme-gen --context "This is a developer tool for internal use"

Or provide context as a positional argument:

readme-gen "Focus on the authentication module"

Target a Specific Package (Monorepos)

readme-gen --package=frontend/

Configuration

Set your API key

If you've already authenticated Claude Code (by running claude in your terminal) with a Pro or Max plan, the SDK uses that authentication automatically.

Otherwise, you can get an API key from the Claude Console and pay per token usage.

Option 1: Environment Variable

export ANTHROPIC_API_KEY="your-api-key"

Option 2: .env File

Create a .env file in your project directory:

ANTHROPIC_API_KEY=your-api-key

| Variable | Required | Description | | ------------------- | -------- | -------------------------------------- | | ANTHROPIC_API_KEY | Yes* | API key for Claude AI (from Anthropic) |

*Not required if you've authenticated Claude Code

Troubleshooting

Tool Permissions in Agent SDK

The tool uses bypassPermissions and allowDangerouslySkipPermissions flags when running agent queries. This allows the agent to explore the filesystem without interactive permission prompts. Ensure you trust the codebase being analyzed.

Development

Prerequisites

• Bun ≥1.3.5

Install Dependencies

bun install

Run Locally

bun start

Scripts

| Command | Description | | -------------------- | ----------------------------------------------- | | bun start | Run the CLI | | bun run check | Format and lint with Biome (auto-fix) | | bun run format | Format code with Biome | | bun test | Run tests | | bun run test:watch | Run tests in watch mode | | bun run qa | Run all quality gates (typecheck + lint + test) |

Quality Gates

Before committing, run:

bun run qa

This runs:

1. TypeScript type checking (tsc --noEmit)
2. Biome format + lint (biome check --write .)
3. All tests (bun test)

Contributing

See CONTRIBUTING.md for development guidelines and quality gate requirements.

License

MIT