Commit with your repository’s rules.

Installation

Install Commitprompt. Conventional Commitlint rules are included, so no separate validation package or configuration is required.

pnpm add --save-dev @santi020k/commitprompt

npm install --save-dev @santi020k/commitprompt

yarn add --dev @santi020k/commitprompt

Configuration

Configuration is optional. Commitprompt uses Conventional Commits rules by default. Add a repository configuration to customize them:

export default {
  rules: {
    // 0 disables a rule, 1 warns, and 2 rejects the message.
    'header-max-length': [0],
    'body-max-line-length': [0],
    'footer-max-line-length': [0],
    'type-enum': [2, 'always', ['feat', 'fix', 'release']]
  }
}

Then expose the neutral binary through your package scripts:

{
  "scripts": {
    "commit": "commitprompt"
  }
}

Commitlint rule tuples use 0 to disable a rule,1 for a warning, and 2 for an error. Commitprompt also passes through repository parser presets, plugins, ignores, default ignores, and help URLs when it validates a message.

Usage

git add src/
pnpm commit

Editor AI commit generation

Configure an editor’s native commit-message generator to use Commitprompt’s Conventional Commit format in every project:

commitprompt setup zed
commitprompt setup vscode

Each command updates the editor’s global settings while preserving comments, model selection, and existing commit-message instructions. They are safe to run more than once. The VS Code integration configures GitHub Copilot’s commit-message generation instructions; Copilot must be enabled for its Source Control button to be available.

Commit format

The generated message follows the Conventional Commits structure:

type(scope)!: short description

Optional longer description.

BREAKING CHANGE: optional breaking change

Closes #123

The type, subject, body, footer, and any repository-specific constraints are checked by Commitlint before confirmation.

Repository rules

A repository configuration takes precedence over Commitprompt’s included defaults. Custom types appear in the prompt, and a message that fails validation can be revised without restarting the CLI.

Git hooks

Commitprompt validates every message created through its own commit flow. It does not currently install Git hooks, so a commit created directly by Git or an editor does not pass through Commitprompt.

To enforce the same policy for every commit, configure Commitlint in your repository’s commit-msg hook. Apre-commit hook runs before the commit message exists and is better suited to staged-file checks.

Automation and AI tools

AI tools can discover the repository’s allowed types, read generation instructions, format structured answers, and validate the exact result without parsing terminal prompts or bypassing repository rules.

commitprompt instructions --json
commitprompt types --json

commitprompt format --json <<'JSON'
{
  "type": "feat",
  "scope": "cli",
  "subject": "accept structured input",
  "body": "",
  "breaking": "",
  "issues": ""
}
JSON

printf '%s\n' 'feat(cli): accept structured input' \
  | commitprompt validate --json

The format and commit commands read a JSON object from stdin by default. Every field is a string; optional values use an empty string. Use --input <path> to read a file and --cwd <path> to target another repository.

Programmatic API

The same Git, prompt, formatting, and validation pieces are exported independently, so you can compose a custom flow without shelling out to the CLI.

import {
  createCommitlintValidator,
  createGitClient,
  runCommitFlow
} from '@santi020k/commitprompt'

const validator = createCommitlintValidator(process.cwd())

await runCommitFlow({
  error: console.error,
  git: createGitClient(process.cwd()),
  log: console.log,
  prompt,
  types: await validator.getTypes(),
  validator
})

Requirements

• Node.js 22.18 or newer
• Git
• At least one staged change