@moretocontabilidade/cmsg

CLI for generating commit messages from staged Git changes using the OpenAI API.

Requirements

1. Node.js 18.18 or newer
2. Git
3. An OpenAI API key (configured via cmsg --init)

Installation

Install the package:

yarn add -D @moretocontabilidade/cmsg

Add the script to package.json:

{
  "scripts": {
    "cmsg": "cmsg"
  }
}

Setup

Run the setup wizard to configure your OpenAI API key:

yarn cmsg --init

The key is stored in ~/.config/cmsg/config with restricted permissions (600) and is reused automatically on every run.

To remove the key:

yarn cmsg --unset

Usage

Run the assistant:

yarn cmsg

If no files are staged, the CLI will ask whether you want to stage all changed files (git add .) before continuing.

You can optionally provide a preferred prefix:

yarn cmsg bug
yarn cmsg chore
yarn cmsg docs
yarn cmsg feature
yarn cmsg improvement

Show help:

yarn cmsg --help

Check the installed version:

yarn cmsg --version

How it works

1. If no staged changes are found, asks whether to run git add .
2. Reads staged changes and filters out lock files, build artifacts, and minified files to reduce token usage
3. Sends the filtered diff to the OpenAI API (model gpt-4o-mini) with structured output
4. Presents one recommended commit message and three alternatives, plus a Try again option
5. If Try again is selected, re-runs the request
6. Runs git commit -m "<selected message>"
7. Optionally runs git pull --rebase and git push

Environment variables

OPENAI_API_KEY

Overrides the key stored by --init. Useful for CI or when you prefer to manage the key yourself.

CMSG_DEBUG

When set to 1, prints the raw API response and token usage instead of the progress spinner.

export CMSG_DEBUG=1

Publishing

Before publishing, log in to npm:

npm login --registry https://registry.npmjs.org

Check what will be included in the package:

yarn pack:check

Publish to npm:

yarn pack:publish

Notes

1. The tool analyzes only staged changes
2. Lock files (*.lock, package-lock.json, etc.), build artifacts (dist/, build/, .next/, etc.), minified files, and source maps are excluded from the diff automatically
3. Large per-file diffs are truncated at 300 lines; the total diff is capped at 20,000 characters
4. Commit messages are always requested in English
5. The CLI is interactive and expects a terminal when prompting for prefix, selection, and sync confirmation