@moretocontabilidade/cmsg

CLI for generating commit messages from staged Git changes using the OpenAI API. It is intended to standardize commit writing across Moreto repositories while keeping the final message grounded in the current diff.

This README is an onboarding document. Its goal is to help a developer install, configure, run, and publish the package safely. Product-specific usage details should stay concise here, while deeper internal decisions can be documented elsewhere if needed.

Tech Stack

• Node.js
• OpenAI API
• Native Git CLI

Prerequisites

Required:

• Node.js 18.18 or newer
• Git available locally
• Package manager: Yarn 1
• An OpenAI API key

Recommended:

• VS Code
• AI assistant: Claude Code or OpenAI Codex

Enabling Yarn

If Yarn is not available after installing Node, enable it with:

corepack enable

Use Yarn for local development commands in this repository.

Getting Started

1. Clone and install dependencies

git clone <repo-url>
cd codex-commit-msg
yarn install

2. Configure your OpenAI API key

Run the setup wizard:

yarn start --init

The key is stored in ~/.config/cmsg/config with restricted permissions and reused automatically on the next runs.

To remove the stored key:

yarn start --unset

3. Run the CLI locally

yarn start

If no files are staged, the CLI asks whether it should run git add . before continuing.

4. Validate the local setup

yarn test

Installation in Another Project

Install the package:

yarn add -D @moretocontabilidade/cmsg

Then run:

yarn cmsg --init

Updating in Another Project

To force another repository to use the latest published version:

yarn add -D @moretocontabilidade/cmsg@latest

Confirm the installed version:

yarn cmsg --version

Usage

Standard usage:

yarn cmsg

After the optional label prompt, the CLI asks for a brief commit description. Press Enter to keep the standard diff-based flow, or type a description to generate commit message alternatives from that text without sending the diff to the OpenAI API.

You can optionally force a preferred prefix:

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

Other commands:

yarn cmsg --help      # Show help
yarn cmsg --version   # Show the installed version
yarn cmsg --unset     # Remove the stored API key

How It Works

1. Reads staged changes only.
2. If no staged changes are found, asks whether it should run git add ..
3. Asks for an optional preferred label.
4. Asks for an optional brief commit description.
5. If a description is provided, generates three English commit message alternatives from that text without sending the diff.
6. If no description is provided, filters lockfiles, build artifacts, minified files, and source maps out of the diff.
7. For small diffs, sends one truncated staged diff directly to the final model.
8. For large or multi-file diffs, splits the staged diff by file, asks an analysis model to summarize each file or large-file chunk, then sends the consolidated summaries to the final model.
9. Lets the user choose a suggestion or retry.
10. Runs git commit -m "<selected message>".
11. Optionally runs git pull --rebase and git push.

Environment Variables

This project does not use .env files or environment-based configuration as its primary setup model.

The main credential used by the CLI is the OpenAI API key provided by the user during initialization with --init, and then stored in ~/.config/cmsg/config.

Optional environment variables:

• OPENAI_API_KEY Overrides the key stored by --init. Useful for CI or when you prefer to manage credentials outside the local config file.
• CMSG_MODEL Default OpenAI model used when a stage-specific model is not set.
• CMSG_ANALYSIS_MODEL Model used in the first pass to summarize file-level diffs. Defaults to CMSG_MODEL or gpt-4o-mini.
• CMSG_FINAL_MODEL Model used in the final pass to generate commit message suggestions. Defaults to CMSG_MODEL or gpt-4o-mini.
• CMSG_ANALYSIS_MODE Controls the analysis strategy: auto, single, or multi. Defaults to auto.
• CMSG_DEBUG When set to 1, prints the raw API response and token usage instead of the progress spinner.

export CMSG_DEBUG=1
export CMSG_ANALYSIS_MODEL=gpt-4o-mini
export CMSG_FINAL_MODEL=gpt-4o

Main Scripts

yarn start         # Run the CLI locally from this repository
yarn test          # Run the test suite
yarn pack:check    # Preview the npm package contents
yarn pack:publish  # Publish the package to npm

Publishing

Before publishing:

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

Then validate the package contents:

yarn pack:check

Publish to npm:

yarn pack:publish

Be intentional when publishing. This repository produces a reusable npm package, so publishing creates a new version for downstream consumers.

Project Structure

bin/
└── cmsg.js    # Thin executable entrypoint

src/
└── cli.js     # Main CLI implementation

test/
└── cli.test.js # Automated tests

Working Agreements

• use this tool only with staged changes;
• keep commit messages in English;
• use Yarn for local development commands in this repository;
• avoid turning this README into exhaustive implementation documentation;
• review package contents before publishing to npm.