Plugins

Plugins extend commit.config.ts with commit rules, AI suggestions, and custom validation. Register them in order inside defineConfig({ plugins: [...] }).

Built-in plugins

conventionalCommits

Required. Defines allowed commit types and optional scopes.

conventionalCommits({
  types: ["feat", "fix", "docs", "chore"],
  scopes: ["web", "cli"],
  strictScopes: true,
});

Plugin ID: conventional-commits

aiSuggest

Enables AI message suggestions during bc commit and bc fix.

aiSuggest({
  provider: "auto",
  model: "gpt-4o-mini",
  customPrompt: "Use imperative mood.",
  allowUnsanitized: false,
});

Plugin ID: ai-suggest

stacking

Enables commit-level stacking by automatically appending stable Change-Id footers to your commit messages and enforcing them during checks.

stacking({
  changeId: true,
});

Plugin ID: stacking

See AI providers for provider options and Configuration for the full option table.

Custom plugins

Add plugins with a unique id and optional hooks. Each plugin must set apiVersion: 1.

prepareMessage hooks

Plugins can register hooks.prepareMessage to transform the commit message quietly right before it is written (either during dry-run, in a git prepare-commit-msg hook, or right before a commit).

Example — append issue number to all commit bodies:

{
  id: "add-issue-suffix",
  hooks: {
    prepareMessage: (msg) => `${msg.trim()}\n\nRefs: #42`
  }
}

validateMessage hooks

Plugins can register hooks.validateMessage to run custom checks after built-in conventional commit validation. Hooks run in plugin registration order.

Example — reject WIP in commit subjects:

import { conventionalCommits, defineConfig } from "@better-commit/cli/config";

export default defineConfig({
  plugins: [
    conventionalCommits({ types: ["feat", "fix", "docs", "chore"] }),
    {
      id: "my-rules",
      hooks: {
        validateMessage: (msg) =>
          msg.includes("WIP")
            ? { valid: false, errors: ["Avoid WIP in commits"], warnings: [] }
            : { valid: true, errors: [], warnings: [] },
      },
    },
  ],
});

Return shape:

Hooks may be synchronous or async. Multiple hooks from different plugins run sequentially.

Rules and AI in one plugin

A single plugin object can combine rules, ai, and hooks. Built-in helpers (conventionalCommits, aiSuggest) are the recommended way to set those fields — use custom plugins for validation logic that does not fit the built-ins.

Plugin requirements

• conventionalCommits() must appear exactly once in the plugins array.
• Plugin id values must be unique.
• Import helpers from @better-commit/cli/config.

Run bc doctor to confirm plugins load and rules resolve correctly.