AI-Enhanced Changelogs

Use AI (Claude Code or any Vercel AI SDK model) to turn raw commit-based changelogs into polished release notes and social media posts.

What it does

Relizy can pass your commit-based changelog through an AI model (Claude Code by default, or any model of the Vercel AI SDK) to produce cleaner, more readable content for:

GitHub / GitLab release notes — commits get rewritten into end-user-facing prose while the compare link and contributor list stay untouched.
Twitter — a short, plain-text announcement that fits within the character limit.
Slack - a concise summary for your release channel, written in standard markdown and rendered with the Slack changelogFormat.

Under the hood, Relizy:

Builds the raw changelog from your commits (as before).
Sends only the body to the model with a target-specific system prompt.
Reassembles the final output: compare link + AI body + contributors (for provider releases), or pipes AI output into your template (for social).

The raw changelog remains the source of truth. PR/issue references, commit scopes, and links are preserved exactly. Nothing is invented.

When to enable it

Turn AI on when you want:

Release notes that read like a human wrote them, without manual editing.
Platform-appropriate social posts (short for Twitter, structured for Slack) from the same source.
Consistent tone across every release.

AI is off by default. With it disabled, Relizy behaves exactly like before. You can also toggle AI per-target or globally via the CLI.

Setup

Relizy supports two AI providers:

Provider	Models	Requirements
`claude-code` (default)	Claude (Haiku by default)	`@yoloship/claude-sdk`, the `claude` CLI, an Anthropic credential
`ai-sdk`	Any Vercel AI SDK model: OpenAI, Google, Mistral, Anthropic, ...	`ai` and the package of your provider

Set up one of them, then enable AI.

Option A: Claude Code (default)

1. Install the Claude SDK

It's an optional peer dependency — you only need it when AI is enabled.

pnpmnpmyarn

bash

pnpm add -D @yoloship/claude-sdk

bash

npm install -D @yoloship/claude-sdk

bash

yarn add -D @yoloship/claude-sdk

2. Install the `claude` CLI binary

The SDK spawns the claude CLI under the hood, so the binary must be on PATH.

bash

# npm (global) — works everywhere, recommended for CI
npm install -g @anthropic-ai/claude-code

# Homebrew (macOS)
brew install --cask claude-code

# Native installer
curl -fsSL https://claude.ai/install.sh | bash

In CI, add a step before running Relizy:

yaml

- name: Install Claude Code CLI
  run: npm install -g @anthropic-ai/claude-code

3. Provide credentials

Export your Anthropic API key (recommended for CI):

bash

export RELIZY_ANTHROPIC_API_KEY="sk-ant-..."
# or, if you prefer the vendor-standard name:
export ANTHROPIC_API_KEY="sk-ant-..."

If you use Claude Code's OAuth flow instead, export the token:

bash

export RELIZY_CLAUDE_CODE_OAUTH_TOKEN="..."
# or
export CLAUDE_CODE_OAUTH_TOKEN="..."

Credentials can also live in your config file — see Credential resolution.

Option B: Vercel AI SDK

1. Install the AI SDK and your provider

Both are optional peer dependencies, only needed when AI is enabled. Pick the package of your provider (@ai-sdk/openai, @ai-sdk/google, @ai-sdk/mistral, ...):

pnpmnpmyarn

bash

pnpm add -D ai @ai-sdk/openai

bash

npm install -D ai @ai-sdk/openai

bash

yarn add -D ai @ai-sdk/openai

2. Set the model

// relizy.config.ts
import { openai } from '@ai-sdk/openai'
import { defineConfig } from 'relizy'

export default defineConfig({
  ai: {
    provider: 'ai-sdk',
    providers: {
      'ai-sdk': { model: openai('gpt-5-mini') },
    },
  },
})

Every provider works the same way, e.g. google('gemini-2.5-flash') from @ai-sdk/google. A model id of the Vercel AI Gateway also works without any provider package: model: 'openai/gpt-5-mini'.

3. Provide credentials

Relizy does not handle the credentials of the AI SDK: the package of your provider reads its own environment variable, e.g. OPENAI_API_KEY for @ai-sdk/openai, GOOGLE_GENERATIVE_AI_API_KEY for @ai-sdk/google, or AI_GATEWAY_API_KEY for a gateway model id.

bash

export OPENAI_API_KEY="sk-..."

To pass the key explicitly, create the provider instance yourself, see providers['ai-sdk'].model.

Enable AI in your config

// relizy.config.ts
import { defineConfig } from 'relizy'

export default defineConfig({
  ai: {
    providerRelease: { enabled: true },
    social: {
      twitter: { enabled: true },
      slack: { enabled: true },
    },
  },
})

That's all — your next release will have AI-rewritten notes.

Model

With `claude-code`

By default Relizy uses the haiku alias — fast and cheap, which is the right profile for short rewrites. Pick a different alias or a fully versioned id if you want more depth:

export default defineConfig({
  ai: {
    providers: {
      'claude-code': { model: 'sonnet' }, // or 'opus', or 'claude-sonnet-4-6'
    },
  },
})

See the full reference in AI Configuration.

With `ai-sdk`

The model is the one you set in providers['ai-sdk'].model. A small, fast model is enough for these short rewrites. For the models that support reasoning, you can lower the effort to make the rewrite faster and cheaper:

export default defineConfig({
  ai: {
    provider: 'ai-sdk',
    providers: {
      'ai-sdk': { model: openai('gpt-5-mini'), reasoning: 'low' },
    },
  },
})

See reasoning.

Preview with `--dry-run`

In dry-run mode, the AI call does execute — that's the point of the preview — but nothing is published. You'll see the rewritten output in Relizy's log boxes, and the API calls to GitHub, GitLab, Twitter, and Slack are skipped.

bash

relizy release --patch --dry-run

In the output you'll see things like:

ℹ ✨ Rewriting release notes with AI (provider: claude-code)
ℹ ✅ AI rewrite done in 1240ms (612 → 431 chars)

┌────────────────────────────────────┐
│ [dry-run] Release Preview          │
│ Tag: v2.1.0                        │
│ ...rewritten body here...          │
└────────────────────────────────────┘

For deeper inspection, bump the log level:

bash

relizy release --patch --dry-run --log-level verbose

This prints the full system prompt, the raw input, and the AI output for every target.

Per-target control

Each target is independent. Enable only what you need:

export default defineConfig({
  ai: {
    providerRelease: { enabled: true }, // GitHub/GitLab: ON
    social: {
      twitter: { enabled: true }, // Twitter: ON
      slack: { enabled: false }, // Slack: OFF (keep raw)
    },
  },
})

CLI flags

Override config at runtime:

bash

# Force AI on for this run (all applicable targets)
relizy release --patch --ai
relizy provider-release --ai
relizy social --ai

# Force AI off for this run
relizy release --patch --no-ai

--ai / --no-ai override whatever is in the config file for the duration of the command.

Customizing the output

Extra guidelines — add rules on top of defaults

The most common case. Appended to every built-in prompt.

export default defineConfig({
  ai: {
    extraGuidelines: [
      'Lead with breaking changes when present.',
      'Never mention the internal codename "Phoenix".',
      'When scope is "api", start the line with "API:".',
    ].join('\n'),
  },
})

System prompt overrides — take full control

Replace the built-in prompt for a specific target. You own everything when you do this — the base prompt is not included.

export default defineConfig({
  ai: {
    systemPromptOverrides: {
      providerRelease: 'Write a blog-style post. Use H2 headers. Output language: {{language}}.',
      twitter: 'One hype tweet. Max {{maxLength}} chars. No hashtags.',
      // slack not set → built-in Slack prompt is used
    },
  },
})

Placeholders available: everywhere, plus for Twitter.

Non-English output

export default defineConfig({
  ai: {
    language: 'fr',
    extraGuidelines: 'Garde les noms de packages et les références en anglais.',
  },
})

Fallback behavior

If the AI call fails — network error, quota, invalid credentials — Relizy decides based on ai.fallback:

Mode	Behavior
`'raw'` (default)	Log a warning and use the unmodified changelog. Release continues.
`'fail'`	Re-throw with context. The release aborts.

export default defineConfig({
  ai: {
    fallback: 'fail', // strict mode — don't ship raw when AI was expected
  },
})

Pick 'raw' for most workflows. Pick 'fail' in CI where AI-enhanced content is contractual.

Cost and latency

With claude-code, Claude Haiku (the default) is fast and inexpensive. A typical call for release notes processes a few hundred tokens and completes in 1–3 seconds. With ai-sdk, cost and latency depend on the model you choose.

Counts per release:

Provider release: 1 call (or 1 per package in independent mode).
Social: 1 call per enabled platform.

Use --dry-run while you're tuning prompts to avoid spending on trial runs that don't publish.

Before / after

Provider release — raw commits

### 🚀 Enhancements

- **auth**: add OAuth2 PKCE flow support (abc1234)
- **api**: implement rate limiting middleware (#142)

### 🩹 Fixes

- **core**: fix memory leak in connection pool (def5678)

#### ⚠️ Breaking Changes

- **auth**: remove deprecated session-based auth (#138)

Provider release — AI-rewritten

### 🚀 Enhancements

- **auth**: Added OAuth2 PKCE flow support for public clients needing safer login (abc1234)
- **api**: Introduced rate-limiting middleware to protect endpoints from abuse (#142)

### 🩹 Fixes

- **core**: Fixed a memory leak in the connection pool that could build up under sustained load (def5678)

#### ⚠️ Breaking Changes

- **auth**: Removed deprecated session-based authentication (#138). Migrate to OAuth2 or token auth.

Compare link and contributors section are added back automatically around this body — they never touch AI.

Twitter — AI-rewritten (inside your template)

Template:

📣 {{projectName}} {{newVersion}} is out!

{{changelog}}

{{releaseUrl}}

Result:

📣 my-app 2.1.0 is out!

OAuth2 PKCE support for safer public-client login, rate-limiting to keep endpoints healthy, and a connection-pool memory leak is gone.

https://github.com/user/my-app/releases/tag/v2.1.0

Slack — AI-rewritten

• *OAuth2 PKCE flow* — safer login for public clients
• *Rate-limiting middleware* — protects API endpoints
• *Memory leak fix* — connection pool under sustained load

Troubleshooting

"No authentication credential found"

With claude-code, no API key or OAuth token reached the provider. Check:

bash

echo $RELIZY_ANTHROPIC_API_KEY
echo $ANTHROPIC_API_KEY
echo $CLAUDE_CODE_OAUTH_TOKEN

Or set it directly in config — see Credential resolution.

"@yoloship/claude-sdk is not installed"

Install it:

bash

pnpm add -D @yoloship/claude-sdk

"The `claude` CLI binary was not found on PATH"

The SDK needs the Claude Code CLI to run. Install it:

bash

npm install -g @anthropic-ai/claude-code

In CI, add it as a step before running Relizy. See Installation.

"No model configured for the ai-sdk provider"

With provider: 'ai-sdk', set the model in ai.providers['ai-sdk'].model, see Option B: Vercel AI SDK.

"ai is not installed"

Install the AI SDK, along with the package of your provider:

bash

pnpm add -D ai @ai-sdk/openai

The ai-sdk provider fails at runtime

The error of the provider package is in the warning (or in the error with fallback: 'fail'). The most common cause is a missing API key: check the environment variable read by your provider package (e.g. OPENAI_API_KEY). Preview with --dry-run to see it before releasing.

"Unknown AI provider"

You set ai.provider to something Relizy doesn't know: use 'claude-code' or 'ai-sdk'. See Adding a new AI provider if you want to plug your own.

The AI output isn't what I want

Preview with --dry-run --log-level verbose to see the exact prompt and input.
Start with extraGuidelines — it's the lightest lever.
Move to systemPromptOverrides for a target when you need full control.

Rate limiting

The default fallback: 'raw' means a rate-limited request simply falls back to the unmodified changelog. For heavy release cadence, consider:

Using a lower-volume model or spacing releases.
--no-ai for non-critical releases.

Next steps

AI Configuration reference — every option with types and defaults
Provider release CLI — command reference
Social CLI — command reference
Twitter integration — Twitter-specific tuning
Slack integration — Slack-specific tuning

AI-Enhanced Changelogs ​

What it does ​

When to enable it ​

Setup ​

Option A: Claude Code (default) ​

1. Install the Claude SDK ​

2. Install the claude CLI binary ​

3. Provide credentials ​

Option B: Vercel AI SDK ​

1. Install the AI SDK and your provider ​

2. Set the model ​

3. Provide credentials ​

Enable AI in your config ​

Model ​

With claude-code ​

With ai-sdk ​

Preview with --dry-run ​

Per-target control ​

CLI flags ​

Customizing the output ​

Extra guidelines — add rules on top of defaults ​

System prompt overrides — take full control ​

Non-English output ​

Fallback behavior ​

Cost and latency ​

Before / after ​

Provider release — raw commits ​

Provider release — AI-rewritten ​

Twitter — AI-rewritten (inside your template) ​

Slack — AI-rewritten ​

Troubleshooting ​

"No authentication credential found" ​

"@yoloship/claude-sdk is not installed" ​

"The claude CLI binary was not found on PATH" ​

"No model configured for the ai-sdk provider" ​

"ai is not installed" ​

The ai-sdk provider fails at runtime ​

"Unknown AI provider" ​

The AI output isn't what I want ​

Rate limiting ​

Next steps ​

AI-Enhanced Changelogs

What it does

When to enable it

Setup

Option A: Claude Code (default)

1. Install the Claude SDK

2. Install the `claude` CLI binary

3. Provide credentials

Option B: Vercel AI SDK

1. Install the AI SDK and your provider

2. Set the model

3. Provide credentials

Enable AI in your config

Model

With `claude-code`

With `ai-sdk`

Preview with `--dry-run`

Per-target control

CLI flags

Customizing the output

Extra guidelines — add rules on top of defaults

System prompt overrides — take full control

Non-English output

Fallback behavior

Cost and latency

Before / after

Provider release — raw commits

Provider release — AI-rewritten

Twitter — AI-rewritten (inside your template)

Slack — AI-rewritten

Troubleshooting

"No authentication credential found"

"@yoloship/claude-sdk is not installed"

"The `claude` CLI binary was not found on PATH"

"No model configured for the ai-sdk provider"

"ai is not installed"

The ai-sdk provider fails at runtime

"Unknown AI provider"

The AI output isn't what I want

Rate limiting

Next steps