relnote

Release notes, curated for humans. relnote reads the commits since your last tag and asks Claude Code — your existing subscription, no API keys — to turn them into release notes end users actually want to read.

Self-bootstrapped: the v0.2.0 release notes were written by relnote itself — then reviewed by a human, as intended.

한국어 README

Not a changelog generator — a curator. It judges each commit by its subject and body, keeps only what users will notice, merges related commits into single entries, translates internal jargon into user value, and lists everything it left out (with reasons) so reviewers can audit its judgment.

Install

brew install agiletalk/tap/relnote

Or build from source:

git clone https://github.com/agiletalk/relnote.git
cd relnote && swift build -c release
cp .build/release/relnote /usr/local/bin/

Requirements

git, plus one of the following (checked in this order by --executor auto):

Executor	Needs	Quality	Cost
claude	Claude Code CLI, signed in — uses your existing Claude subscription, no API keys	best	subscription usage
apple	macOS 26+ with Apple Intelligence — Apple's on-device model, nothing to install	good for small releases; noticeably below Claude	free, offline
--no-llm	nothing	deterministic Conventional Commits grouping, no curation	free, offline

The on-device model has a small (~4k token) context window and is strongest in English — for large ranges or nuanced curation, prefer claude.

Usage

relnote                        # notes for last tag → HEAD, markdown to stdout
relnote --lang ko              # Korean notes
relnote --from v1.2.0 --to v1.3.0
relnote --format json | jq .  # structured output
relnote --no-llm               # deterministic, offline
relnote -C ~/code/my-app > RELEASE_NOTES.md

If HEAD is exactly at your latest tag (you just cut a release), relnote automatically steps back one tag — so bare relnote right after tagging gives you the notes for that release, not an empty range.

Options

Flag	Default	Description
--from <ref>	latest tag	Start of the commit range (exclusive)
--to <ref>	HEAD	End of the commit range (inclusive)
--version-name <name>	tag at --to, or Unreleased	Version shown in the notes
--format <md|json>	md	Output format
--lang <en|ko>	en	Notes language
--no-llm	off	Skip the LLM; group conventional commits offline
--executor <auto|claude|apple>	auto	auto = claude if installed, else the Apple on-device model
--model <model>	claude's default	Passed through to claude --model (claude executor only)
-C <dir>	.	Run as if started in <dir>
--max-commits <n>	200	Cap on commits fed to curation
--timeout <s>	300	Timeout for the claude invocation
--verbose	off	Diagnostics on stderr (range resolution, cost, session id)

Notes go to stdout; progress and warnings go to stderr, so piping and redirection stay clean.

How it works

1. Range — finds the latest tag reachable from --to (git describe) and uses tag..HEAD. No tags? Falls back to recent history with a warning.
2. Parse — reads the log with field-separator formatting, classifies each commit against Conventional Commits (type, scope, !/BREAKING CHANGE:).
3. Curate — sends subjects and bodies to claude -p with a JSON schema (--json-schema), which returns validated structured output: one hero change, up to 6 highlights, and an excluded list with reasons. version and date are injected from git, never generated.
4. Render — markdown (or raw JSON with --format json).

Output schema (--format json)

{
  "version": "v2.10.0",
  "date": "2026-07-13",
  "hero": { "title": "…", "description": "…" },
  "highlights": [{ "title": "…", "description": "…" }],
  "excluded": [{ "commit": "…", "reason": "…" }]
}

Roadmap

• Slack Block Kit renderer + webhook delivery
• relnote publish — update GitHub Release bodies in place
• More --executor backends: Codex CLI, GitHub Copilot CLI, opencode (subscription-based, like claude), plus bring-your-own-key APIs and Ollama (local)
• Linux support

License

MIT © Chanju Jeon