changelog-ai

Generate professional CHANGELOG entries from git history — in seconds.

changelog-ai                           # unreleased since last tag
changelog-ai --release-version v1.2.0  # label the release
changelog-ai --format github           # GitHub Releases format
changelog-ai --prepend CHANGELOG.md   # write to file

---

The problem

Writing a CHANGELOG is one of the most tedious tasks in software development:

"Okay, I have 43 commits since v1.0.0... let me read each one and figure out what to say."

You already wrote the commits. Why are you also writing about them?

changelog-ai reads your git history and writes the CHANGELOG for you.

Even with messy commit messages. Even without conventional commits.

---

Why changelog-ai?

git-cliff (3.2k stars) and conventional-changelog are great — if you write perfect conventional commits.

changelog-ai goes further:

Feature	changelog-ai	git-cliff	conv-changelog
Works with messy commits	✅	❌	❌
AI-summarized descriptions	✅	❌	❌
Groups related commits	✅	limited	limited
Keep a Changelog format	✅	✅	✅
GitHub Releases format	✅	✅	✅
Local LLM support (Ollama)	✅	❌	❌
Breaking change detection	✅	✅	✅

---

Install

pip install changelog-ai

Or with pipx (recommended):

pipx install changelog-ai

---

Quick Start

# Auto-detects provider from env (ANTHROPIC_API_KEY or OPENAI_API_KEY)
changelog-ai

# Label the release version
changelog-ai --release-version v1.2.0

# Generate for a specific range
changelog-ai --from v1.0.0 --to v1.1.0

# GitHub Releases format
changelog-ai --format github

# Write to CHANGELOG.md
changelog-ai --release-version v1.2.0 --prepend CHANGELOG.md

# Preview without writing
changelog-ai --prepend CHANGELOG.md --dry-run

# List available tags
changelog-ai --list-tags

# No API key needed
changelog-ai --provider ollama --model llama3.2

---

Formats

--format keepachangelog (default)

Follows Keep a Changelog spec with Added, Changed, Fixed, Security, Breaking Changes sections.

--format github

GitHub Release Notes style with "What's Changed" summary.

--format minimal

Simple bullet list — great for internal changelogs.

---

Providers

Provider	Flag	Requires
Claude (default if key exists)	--provider claude	ANTHROPIC_API_KEY
OpenAI	--provider openai	OPENAI_API_KEY
Ollama (local, free)	--provider ollama	Ollama running

---

Options

changelog-ai [PATH] [OPTIONS]

Ref range:
  --from REF            Start ref (tag, SHA, branch). Defaults to latest tag.
  --to REF              End ref [default: HEAD]

Release info:
  --release-version VER Version label (e.g. v1.2.0) [default: Unreleased]
  --date DATE           Release date YYYY-MM-DD [default: today]

Format:
  --format              keepachangelog | github | minimal [default: keepachangelog]

Output:
  --prepend FILE        Prepend entry to this file
  --dry-run             Preview without writing
  --raw                 Plain text output (no formatting)

Utilities:
  --list-tags           List recent tags and exit
  --show-commits        Show commits found before generating
  -V, --version         Show version
  -h, --help            Show help

---

GitHub Actions

Use changelog-ai-action to automate changelog generation in CI:

# .github/workflows/changelog.yml
on:
  release:
    types: [created]

jobs:
  changelog:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: faw21/changelog-ai-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          post_to_release: 'true'   # updates Release body
          commit_changelog: 'true'  # commits CHANGELOG.md

---

Tips

# Release workflow
changelog-ai --list-tags                                          # see last release
changelog-ai --release-version v1.3.0 --dry-run                  # preview
changelog-ai --release-version v1.3.0 --prepend CHANGELOG.md     # commit it

# GitHub Release automation
changelog-ai --format github --raw > release-notes.txt
gh release create v1.3.0 --notes-file release-notes.txt

---

Related Tools

gitbrief — Pack the right files from any repo into LLM-ready context.

gpr — AI-powered PR descriptions and commit messages.

standup-ai — Generate daily standups from git commits.

critiq — AI code reviewer that runs locally before you push.

git-chronicle — AI-powered git history narrator. Turns your git log into engaging stories (narrative, timeline, or detective mode).

prcat — AI reviewer for teammates' pull requests. Summarizes, flags risks, and suggests review comments.

# The complete AI-powered git workflow:
standup-ai --yesterday                                    # 1. morning standup
critiq                                                    # 2. AI review before committing
testfix pytest                                            # 3. Auto-fix failing tests
gpr --commit-run                                          # 4. commit with AI message
gitbrief . --changed-only --clipboard                    # 5. pack context for PR review
gpr                                                       # 6. generate PR description
prcat 42                                                  # 7. AI review of teammate's PR
changelog-ai --release-version v1.x.0 --prepend CHANGELOG.md  # 8. update changelog

---

Development

git clone https://github.com/faw21/changelog-ai
cd changelog-ai
python -m venv .venv && source .venv/bin/activate
.venv/bin/pip install -e ".[dev]"
pytest tests/   # 49 tests, 87% coverage

---

• difftests — AI test generator from git diffs

• changelog-ai-action — this tool as a GitHub Action (auto-generate changelog on release)

• critiq-action — critiq as a GitHub Action for CI

• testfix — AI failing test auto-fixer

• mergefix — AI merge conflict resolver: fix all conflicts with one command

License

MIT