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

Project setup

Configure package metadata, repository enforcement, and AI instructions in one idempotent operation:

commitprompt setup project

Setup detects npm, pnpm, or Yarn; adds Commitprompt and Husky as development dependencies; sets the neutral commitscript; installs a commit-msg validation hook; and adds guarded guidance to AGENTS.md and GitHub Copilot instructions plus reusable agent skills. Run the detected package manager’s install command afterward to update the lockfile and activate Husky.

Run commitprompt setup editors to create tracked, repository-aware instructions in .vscode/settings.jsonand .zed/settings.json. Configured commit types and scopes are included without writing model preferences.

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']],
    'scope-enum': [2, 'always', ['cli', 'docs']]
  }
}

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. JavaScript, JSON, YAML, and erasable TypeScript configuration files load through Node.js without adding TypeScript to consumer dependencies.

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

Repository rules and extended configurations take precedence over Commitprompt’s included defaults. Custom types and scopes appear in the prompts, and a message that fails validation can be revised without restarting the CLI. Without scope-enum, scope remains optional and free-form.

Git hooks

Project setup installs a Husky commit-msg hook that runscommitprompt validate --input "$1". It preserves unrelated hook commands and replaces known package-manager-specific Commitlint invocations.

The hook enforces the same repository rules for commits created directly by Git, Zed, or VS Code. A pre-commit hook runs before the commit message exists and is better suited to staged-file checks.

npx --no-install commitprompt validate --input "$1"

pnpm exec commitprompt validate --input "$1"

yarn exec commitprompt validate --input "$1"

On failure, Commitprompt lists the violated rules, states that the commit was blocked, and directs the author to correct the message. The generated neutral command works with npm, pnpm, and Yarn because Husky adds local binaries to PATH.

Automation and AI tools

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

commitprompt instructions --json
commitprompt scopes --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,
  scopes: await validator.getScopes(),
  types: await validator.getTypes(),
  validator
})

Within a major version, additions may extend returned objects, exported unions, or optional options. Existing documented behavior and required inputs will not change incompatibly.

Requirements

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