tldrs - TL;DR for your codebase

tldrs is a powerful command-line tool that automatically generates professional README.md files by analyzing your codebase using Large Language Models (LLMs). Save hours of documentation work and ensure consistency across your projects.

Features

• AI-Powered Analysis - Leverages Google Gemini and OpenAI GPT models
• Smart Codebase Scanning - Intelligently analyzes project structure and dependencies
• Custom Prompts - Use your own prompts or load from files for tailored documentation
• Streaming Mode - Watch your README generate in real-time, section by section
• Multiple LLM Providers - Switch between Gemini and OpenAI based on your preference
• Professional Templates - Generates comprehensive, well-structured documentation
• Additional Instructions - Fine-tune output with custom instructions
• Fast & Efficient - Optimized for speed with smart content filtering

Quick Start

Installation

Install tldrs from crates.io:

bashCopy
cargo install tldrs

Basic Usage

1. Set up your API key (choose one):

bashCopy
# For Google Gemini (recommended - free tier available)
export GEMINI_API_KEY="your-gemini-api-key"

# For OpenAI
export OPENAI_API_KEY="your-openai-api-key"

2. Generate a README:

bashCopy
# In your project directory
tldrs readme

# Or specify a path
tldrs readme /path/to/your/project

3. Your README.md is ready!

How It Works

1. Code Analysis: Scans your project directory, analyzing:

   • Project structure and file organization
   • Configuration files (Cargo.toml, package.json, etc.)
   • Source code patterns and dependencies
   • Documentation and comments

2. Content Extraction: Intelligently filters and prioritizes:

   • Main application logic
   • Configuration and setup files
   • API definitions and interfaces
   • Build and dependency information

3. AI Generation: Sends structured context to your chosen LLM with:

   • System prompt for README generation
   • Your custom prompt (if provided)
   • Additional instructions
   • Extracted code context

4. Output Creation: Generates a professional README.md with:

   • Project overview and description
   • Installation instructions
   • Usage examples and documentation
   • Contributing guidelines
   • License information

Advanced Usage

Command Reference

bashCopy
tldrs readme [OPTIONS] [PATH]

Key Options

• -p, --provider <PROVIDER> - LLM provider (gemini or openai)
• -s, --streaming - Enable real-time streaming mode
• --prompt <PROMPT> - Custom prompt for generation
• --prompt-file <FILE> - Load custom prompt from file
• --instructions <TEXT> - Additional instructions

Examples

bashCopy
# Use OpenAI instead of Gemini
tldrs readme --provider openai

# Watch the README generate in real-time
tldrs readme --streaming

# Use a custom prompt
tldrs readme --prompt "Create a README focusing on installation and basic usage only"

# Load prompt from file
tldrs readme --prompt-file my-custom-prompt.txt

# Add extra instructions
tldrs readme --instructions "Include performance benchmarks"

Custom Prompts

Create a text file with your custom prompt:

textCopy
# example-prompt.txt
You are a technical writer creating documentation for a software project.
Generate a README that includes:
1. A compelling project description
2. Clear installation instructions
3. Basic usage examples
4. API documentation if applicable
5. Contributing guidelines

Focus on clarity and include code examples where relevant.

Use it with:

bashCopy
tldrs readme --prompt-file example-prompt.txt

Performance

• Analysis Speed: Processes most codebases in under 10 seconds
• Generation Time: Typically 15-45 seconds depending on LLM provider and project size
• Memory Usage: Minimal footprint, suitable for CI/CD environments
• Supported Project Sizes: From small scripts to large enterprise codebases

Getting API Keys

Google Gemini (Recommended)

1. Visit Google AI Studio
2. Sign in with your Google account
3. Click "Get API Key" and create a new key
4. Free tier includes generous limits for personal projects

OpenAI

1. Visit OpenAI Platform
2. Sign up or log in to your account
3. Navigate to API Keys section
4. Create a new API key
5. Note: This is a paid service with usage-based billing

Contributing

We welcome contributions! Here's how to get started:

Development Setup

1. Clone the repository:

bashCopy
git clone https://github.com/pixperk/tldrs.git
cd tldrs

2. Install dependencies:

bashCopy
cargo build

3. Run tests:

bashCopy
cargo test

4. Run locally:

bashCopy
cargo run -- readme --help

Contributing Guidelines

• Fork the repository and create a feature branch
• Write tests for new functionality
• Ensure code follows Rust best practices
• Update documentation as needed
• Submit a pull request with a clear description

License

This project is licensed under the MIT License - see the LICENSE file for details.

Built for developers who value good documentation but don't want to spend hours writing it manually.