clgen

AI-powered changelog generator from git history.

Stop spending 30 minutes manually curating release notes. clgen reads your git log, semantically understands your changes using LLMs, and generates professional, audience-specific changelogs in seconds.

English | 简体中文

---

✨ Magic in Action

Before (Raw, messy git log):

feat: add user authentication
fix: resolve login timeout (#12)
chore: update dependencies
feat!: rename send() to request()
Merge branch 'dev' into main

After (Generated by clgen):

👤 User-Facing

• New Features: Added a secure user authentication system.
• Bug Fixes: Resolved an issue where login requests would occasionally timeout.

💻 Developer-Facing

• Breaking Changes: send() has been renamed to request().
  • Migration: Update all instances of send() to request().
• Features: Implemented auth module logic.

---

🚀 Key Features

• Semantic Understanding: Uses LLMs (OpenAI, Anthropic, DeepSeek, etc.) to distinguish between features, fixes, and breaking changes—even without conventional commit tags.
• Multi-Audience Output: Generates three versions:
  • User: Plain language, focused on value.
  • Developer: Technical details, API changes, and migration hints.
  • Summary: A 2-sentence blurb for announcements.
• Zero Config: Automatically detects your last tag and works out of the box.
• Safety First: Supports --dry-run to preview before writing to files.

---

💻 OS Support

Currently, clgen is officially tested and supported on:

• ✅ Windows
• ✅ Linux
• ⏳ macOS (Support pending/not yet officially verified)

---

🛠 Installation

# Recommended (with uv)
uv tool install clgen

# With pip
pip install clgen

---

📖 Quick Start

Ensure you have an API key set (e.g., DEEPSEEK_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY).

# Generate for all audiences (stdout)
clgen --dry-run

# Append to CHANGELOG.md (auto-detects tag..HEAD)
clgen --append

# Specific version range
clgen v1.0.0..HEAD

# Target a specific model
clgen --model deepseek/deepseek-v4-flash

---

⚙️ Configuration & Models

clgen uses litellm for universal provider support.

1. API Keys & Environment Variables

Provider	Environment Variable	Model Flag Example
DeepSeek	DEEPSEEK_API_KEY	--model deepseek/deepseek-v4-flash
OpenAI	OPENAI_API_KEY	--model openai/gpt-4o
Anthropic	ANTHROPIC_API_KEY	--model anthropic/claude-sonnet-4-20250514

2. Configuration Strategy

You can configure your API keys in several ways:

• Windows System Environment Variables: You can set variables via System Properties > Environment Variables. clgen will read these directly.
• .env Files: clgen looks for environment variables in two locations:
  1. %USERPROFILE%\.clgen\.env: Global config (recommended for cross-project use).
  2. ./.env: Project-local config (overrides global settings).

---

⌨️ CLI Reference

Flag	Description	Default
REVISION_RANGE	Git range (e.g. v1.0.0..HEAD)	Last tag to HEAD
-a, --audience	user, developer, summary, or all	all
-o, --output	Output file path	CHANGELOG.md
--append	Prepend to existing content	True
--no-append	Overwrite existing file	False
--dry-run	Print to stdout only	False
-m, --model	LLM model identifier	Auto-detected

---

📄 License

MIT