Opinionated, style-aware AI assistant for crafting and splitting git commits. Provider-agnostic — supports OpenCode-routed models, direct Claude CLI, and direct Anthropic API.

Features • Quick Start • CLI Reference • Configuration • Development

✨ Features

• 🤖 AI-generated conventional commits — reads your staged diff and produces a Conventional Commits-compliant message in one command
• ✂️ Smart commit splitting — clusters hunks semantically and proposes multiple atomic commits, each selectively staged and executed
• 🎨 Gitmoji style support — standard, gitmoji (emoji + type), and gitmoji-pure (emoji only) modes out of the box
• ✏️ Refine & reword — iteratively reshape the last commit's wording or reword any past commit using natural-language instructions
• 🔌 Plugin system — register custom transform and validate hooks to enforce team conventions or post-process candidates
• 🔒 Privacy-aware diff filtering — three tiers (low / medium / high) control exactly how much code is sent to the model
• 🌐 Provider-agnostic — any OpenCode-supported model, direct Claude CLI with no API key, or the Anthropic SDK with your own key

🚀 Quick Start

Install globally:

npm install -g @kud/ai-conventional-commit-cli

Optional shell alias for convenience:

alias aicc='ai-conventional-commit'

Generate a commit from staged changes:

git add .
ai-conventional-commit
# ✔ feat(api): add pagination metadata to list endpoint

Propose and execute multiple 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

Gitmoji style:

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

Auto-confirm without prompts (CI / scripting):

AICC_YES=true ai-conventional-commit

Pick and save your preferred model:

ai-conventional-commit models

📖 CLI Reference

Commands

| Command | Description | | ------------------------------------------------- | -------------------------------------------------------------- | | ai-conventional-commit | Generate a single commit suggestion from staged diff (default) | | ai-conventional-commit generate | Explicit alias of the root command | | ai-conventional-commit split [n] | Cluster staged changes into n commits and execute each | | ai-conventional-commit refine | Refine the last generated commit message | | ai-conventional-commit reword [hash] | AI-assisted reword of an existing commit | | ai-conventional-commit models | List, pick, and save available models | | ai-conventional-commit config show | Show the merged resolved configuration and its sources | | ai-conventional-commit config get <key> | Read a single configuration value | | ai-conventional-commit config set <key> <value> | Persist a configuration value globally |

Flags

| Flag | Description | | ------------------------------------------- | --------------------------------------------- | | --style <standard\|gitmoji\|gitmoji-pure> | Override the commit style for this run | | --model <provider/name> | Override the active model for this run | | -y, --yes | Skip all confirmation prompts | | --shorter | Ask the model to shorten the message (refine) | | --longer | Ask the model to expand the message (refine) | | --scope <scope> | Force a specific scope (refine) |

Reword in detail

# Interactive picker — last 20 commits
ai-conventional-commit reword

# Reword HEAD and amend in-place on acceptance
ai-conventional-commit reword HEAD

# Reword an older commit (prints interactive rebase instructions)
ai-conventional-commit reword <hash>

# With style and model overrides
ai-conventional-commit reword <hash> --style gitmoji --model github-copilot/gpt-4.1

Merge commits (multiple parents) are rejected. Title formatting — gitmoji, normalisation — matches all other commands.

⚙️ Configuration

Configuration is resolved via cosmiconfig in the following precedence order (later wins):

1. Built-in defaults (github-copilot/gpt-4.1)
2. OPENCODE_FREE_MODEL env var
3. Global config — ~/.config/ai-conventional-commit-cli/aicc.json
4. Project config — .aiccrc / .aiccrc.json at the repo root
5. Environment variables (AICC_*)
6. CLI flags (--model, --style, …)

Config file example

{
  "model": "github-copilot/gpt-4.1",
  "privacy": "low",
  "style": "gitmoji",
  "styleSamples": 120,
  "maxTokens": 512,
  "maxFileLines": 1000,
  "skipFilePatterns": ["**/package-lock.json", "**/dist/**", "**/*.d.ts"],
  "plugins": ["./src/plugins/my-plugin.ts"]
}

Environment variables

| Variable | Default | Description | | ------------------- | ------------------------ | ------------------------------------------------------------------- | | AICC_MODEL | github-copilot/gpt-4.1 | Model string, e.g. claude/sonnet or anthropic/claude-sonnet-4-6 | | AICC_STYLE | standard | Commit style: standard, gitmoji, or gitmoji-pure | | AICC_PRIVACY | low | Diff detail level sent to the model | | AICC_YES | — | Set to true to skip all confirmation prompts | | AICC_DEBUG | — | Enable verbose provider logs | | AICC_MAX_TOKENS | 512 | Token limit for model responses | | ANTHROPIC_API_KEY | — | Required when using anthropic/* models |

Providers and models

| Provider | Example model strings | Auth | | ------------------------------ | ----------------------------------------------------------------------------------- | --------------------------- | | OpenCode (any supported model) | github-copilot/gpt-4.1, github-copilot/claude-sonnet-4.6, opencode/big-pickle | OpenCode session | | Claude CLI (no API key needed) | claude/sonnet, claude/opus, claude/haiku | Claude Code auth | | Anthropic SDK (direct API) | anthropic/claude-sonnet-4-6, anthropic/claude-opus-4-7 | ANTHROPIC_API_KEY env var |

Gitmoji modes

| Mode | Example output | Notes | | -------------- | ------------------------- | --------------------------- | | standard | feat: add search box | No emoji | | gitmoji | ✨ feat: add search box | Emoji prefix, type retained | | gitmoji-pure | ✨: add search box | Emoji prefix, type removed |

Privacy modes

| Mode | Data sent to model | | -------- | ------------------------------------------------------ | | low | Hunk headers + first 40 changed/context lines per hunk | | medium | File + hunk hash + line counts + function context only | | high | File names + aggregate add/remove counts only |

Higher privacy reduces stylistic richness. Choose based on your repository's sensitivity.

skipFilePatterns defaults

Lock files (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, Cargo.lock, …), TypeScript declarations (**/*.d.ts), build output (dist/**, build/**, .next/**), and minified assets (*.min.js, *.min.css, *.map) are excluded from the AI prompt by default but are still committed normally. Override via config; set to [] to disable entirely.

OpenCode MCP behaviour

On startup, all MCP servers from your global OpenCode config are automatically disconnected for the duration of this tool's process. This keeps the model's tool count within provider limits (GitHub Copilot caps at 128), removes MCP initialisation latency, and lets the model focus entirely on commit generation. Your global OpenCode setup is unaffected.

Run with AICC_DEBUG=true to see which MCP servers were disconnected.

🔌 Plugin API

Plugins run in two phases over the list of commit candidates:

interface PluginContext {
  cwd: string;
  env: NodeJS.ProcessEnv;
}

interface Plugin {
  name: string;
  transformCandidates?(
    candidates: CommitCandidate[],
    ctx: PluginContext,
  ): CommitCandidate[] | Promise<CommitCandidate[]>;
  validateCandidate?(
    candidate: CommitCandidate,
    ctx: PluginContext,
  ): string | string[] | void | Promise<string | string[] | void>;
}

• transformCandidates — runs once over the full candidate list; use it for normalisation or enrichment
• validateCandidate — runs per chosen candidate before the commit executes; return a string to block with an error message

Example — scope normaliser:

export default {
  name: 'scope-normaliser',
  transformCandidates(candidates) {
    return candidates.map((c) => ({
      ...c,
      title: c.title.replace('(UI)', '(ui)'),
    }));
  },
};

Register plugins via the plugins array in your .aiccrc:

{
  "plugins": ["./src/plugins/scope-normaliser.ts"]
}

🔧 Development

Project structure

src/
├── index.ts          # CLI entry point (clipanion)
├── workflow/         # generate, split, refine, reword flows
├── providers/        # OpenCode, Claude CLI, and Anthropic SDK adapters
├── model/            # Model resolution and listing
├── config.ts         # Cosmiconfig loader + defaults
├── git.ts            # simple-git helpers
├── guardrails.ts     # Title normalisation and length checks
├── style.ts          # Style fingerprint from recent commits
├── title-format.ts   # Gitmoji + conventional format helpers
├── plugins.ts        # Plugin loader and runner
├── prompt.ts         # AI prompt construction
├── cluster.ts        # Hunk clustering for split
├── types.ts          # Shared TypeScript types
└── sample-plugin/    # Example plugin for reference

Scripts

| Script | Description | | -------------------- | ------------------------------------------------- | | npm run dev | Run from source with tsx (no build step needed) | | npm run build | Compile ESM bundle via tsup | | npm test | Run test suite with vitest | | npm run test:watch | Run tests in watch mode | | npm run lint | Lint with ESLint | | npm run format | Format with Prettier |

Local development workflow

git clone https://github.com/kud/ai-conventional-commit-cli.git
cd ai-conventional-commit-cli
npm install

# Run without building
npm run dev -- generate

# Or build and link globally
npm run build
npm link
ai-conventional-commit --help

🏗 Tech Stack

| Package | Role | | ------------------------------------------------------------- | ------------------------------------ | | TypeScript | Language (ESM, strict) | | tsup | ESM bundle compiler | | clipanion | CLI framework and command routing | | @opencode-ai/sdk | OpenCode provider communication | | @anthropic-ai/sdk | Direct Anthropic API provider | | @inquirer/prompts | Interactive terminal prompts | | simple-git | Git operations (diff, stage, commit) | | cosmiconfig | Config file resolution | | zod | Runtime schema validation | | ora | Terminal spinner | | chalk | Terminal colour output | | vitest | Unit testing |

MIT © kud — Made with ❤️