ai-conventional-commit

Features

Everything you need

Opinionated, fast, and batteries-included.

✨

AI-generated commits

Reads your staged diff and produces a Conventional Commits-compliant message in one command. Mirrors your repo's style automatically.

✂️

Smart splitting

The split command clusters hunks semantically and proposes multiple atomic commits, each selectively staged and executed.

🎨

Gitmoji style support

Three modes out of the box: standard, gitmoji (emoji + type), and gitmoji-pure (emoji only).

✏️

Refine & reword

Iteratively reshape the last commit's wording or reword any past commit using natural-language instructions with an interactive picker.

🔒

Privacy-aware filtering

Three tiers — low, medium, high — control exactly how much code is sent to the model. Ideal for sensitive repos.

🔌

Plugin system

Register custom transform and validate hooks to enforce team conventions or post-process candidates before the commit runs.

Quick start

Up and running in seconds

Stage your changes and let AI do the rest.

# Install globally
npm install -g @kud/ai-conventional-commit-cli

# Optional shell alias
alias aicc='ai-conventional-commit'

# Stage your changes, then generate a commit
git add -p
ai-conventional-commit
  ✔ feat(api): add pagination metadata to list endpoint

# Split staged changes into multiple atomic commits
ai-conventional-commit split
  1. refactor(parser): simplify token scanning
  2. feat(parser): support negated glob segments
  3. test(parser): add cases for brace + extglob combos

# Use gitmoji style
ai-conventional-commit --style gitmoji
  ✨ feat(ui): add dark mode toggle

# Skip prompts for CI / scripting
AICC_YES=true ai-conventional-commit

# Pick and save your preferred model
ai-conventional-commit models --interactive --save

Commands

CLI reference

All commands accept --model <provider/name>, --style <standard|gitmoji|gitmoji-pure>, and -y / --yes.

generate

Generate a single commit suggestion from staged diff. This is the default command.

split [n]

Cluster staged changes into n atomic commits and execute each with real selective staging.

refine
--shorter / --longer
--scope <s>

Refine the last generated commit message. Iteratively shorten, expand, or change scope.

reword [<hash>]

AI-assisted reword of an existing commit. Omit hash for interactive picker. HEAD auto-amends in-place.

models
--interactive / -i
--save
--current

List, pick, and persist your preferred AI model globally.

config show
config get <key>
config set <key> <val>

View merged config with sources, read a single key, or persist a value to your global config file.

Providers

Three provider paths

Choose the path that suits your setup. Switch any time via AICC_MODEL or the interactive model picker — no code changes required.

GitHub Copilot

Requires a Copilot subscription

github-copilot/gpt-4.1 github-copilot/claude-sonnet-4-5 github-copilot/gemini-2.0-flash

Claude CLI

Uses Claude Code auth — no API key needed

claude/sonnet claude/opus claude/haiku

Anthropic SDK

Requires ANTHROPIC_API_KEY

anthropic/claude-sonnet-4-6 anthropic/claude-opus-4-5 anthropic/claude-haiku-3-5

Set once via AICC_MODEL or interactively with ai-conventional-commit models --interactive --save.

Configuration

Key environment variables

Place a .aiccrc in your project root or set values globally at ~/.config/ai-conventional-commit-cli/aicc.json. Precedence: defaults → env → global → project → CLI flags.

AICC_MODEL Model string, e.g. claude/sonnet

ANTHROPIC_API_KEY Required when using the anthropic/* provider

AICC_STYLE standard | gitmoji | gitmoji-pure

AICC_PRIVACY Diff detail level: low | medium | high

AICC_YES Set to true to skip all prompts

AICC_DEBUG Enable verbose provider logs